> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dcash.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Deposits (C2B)

> Initiate a customer-to-business deposit transaction

## Endpoint

```
POST /merchants/transactions/c2b
```

## Description

Initiates a fund transfer on behalf of the user. The transaction flow works as follows:

<Steps>
  <Step title="Balance Check">
    System checks if the user has sufficient balance for the requested payment amount
  </Step>

  <Step title="Sufficient Balance">
    If balance is sufficient, the transfer is processed immediately and response is returned
  </Step>

  <Step title="Insufficient Balance">
    If balance is insufficient:

    * **Payment Provider Check**: Verifies whether `payment_provider` is specified in the request
    * **No Provider Specified**: Returns "insufficient balance" response
    * **Provider Specified**: Initiates a deposit transaction through the specified payment provider, returns "transaction pending" response, and once the deposit is successful, funds are transferred to the merchant account
  </Step>

  <Step title="Webhook Notification">
    The result is sent to the provided webhook URL. If no webhook URL is provided, the result is sent to the deposit webhook URL set on the merchant portal
  </Step>
</Steps>

## Headers

<ParamField header="x-api-key" type="string" required>
  Merchant API key for authentication
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token of the authenticated user

  Format: `Bearer {token}`
</ParamField>

## Body Parameters

<ParamField body="reference_id" type="string" required>
  Merchant-provided unique identifier for tracking
</ParamField>

<ParamField body="description" type="string">
  Description of the deposit transaction
</ParamField>

<ParamField body="payment_provider" type="string">
  Payment provider to use (e.g., "mpesa", "airtel")

  Must be one of the providers returned by the [Get Payment Providers](/api-reference/user-management/get-providers) endpoint
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to deposit
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code (e.g., "USD")
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive transaction completion notification
</ParamField>

## Response

<ResponseField name="transaction_id" type="string">
  Unique identifier for the transaction
</ResponseField>

<ResponseField name="reference_id" type="string">
  Merchant-provided reference ID (if provided)
</ResponseField>

<ResponseField name="transaction_status" type="string">
  Current status of the transaction (e.g., "pending")
</ResponseField>

<ResponseField name="amount" type="number">
  Amount of the transaction
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://sandbox.dcash.africa/merchants/transactions/c2b \
    --header 'Authorization: Bearer YOUR_USER_TOKEN' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_MERCHANT_API_KEY' \
    --data '{
      "reference_id": "abcd",
      "description": "Test Deposit",
      "payment_provider": "mpesa",
      "amount": 10,
      "currency": "USD",
      "webhook_url": "https://api.paymaxis.com/webhook/dcash"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://sandbox.dcash.africa/merchants/transactions/c2b', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_MERCHANT_API_KEY',
      'Authorization': 'Bearer YOUR_USER_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference_id: 'abcd',
      description: 'Test Deposit',
      payment_provider: 'mpesa',
      amount: 10,
      currency: 'USD',
      webhook_url: 'https://api.paymaxis.com/webhook/dcash'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://sandbox.dcash.africa/merchants/transactions/c2b"
  headers = {
      "x-api-key": "YOUR_MERCHANT_API_KEY",
      "Authorization": "Bearer YOUR_USER_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "reference_id": "abcd",
      "description": "Test Deposit",
      "payment_provider": "mpesa",
      "amount": 10,
      "currency": "USD",
      "webhook_url": "https://api.paymaxis.com/webhook/dcash"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, "https://sandbox.dcash.africa/merchants/transactions/c2b");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "x-api-key: YOUR_MERCHANT_API_KEY",
      "Authorization: Bearer YOUR_USER_TOKEN",
      "Content-Type: application/json"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      "reference_id" => "abcd",
      "description" => "Test Deposit",
      "payment_provider" => "mpesa",
      "amount" => 10,
      "currency" => "USD",
      "webhook_url" => "https://api.paymaxis.com/webhook/dcash"
  ]));

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Example Response

```json 200 OK theme={null}
{
  "transaction_id": "skjr3",
  "reference_id": "abcd",
  "transaction_status": "pending",
  "amount": 123,
  "currency": "USD"
}
```

<Info>
  When the transaction completes, you'll receive a [webhook notification](/api-reference/webhooks) with the final transaction status and additional details.
</Info>

## Error Codes

| Code                             | Message                                     |
| -------------------------------- | ------------------------------------------- |
| `missing_api_key`                | please provide an api key                   |
| `invalid_api_key`                | api key does not exist                      |
| `authorization_token_not_found`  | please provide a bearer authorization token |
| `invalid_currency`               | invalid currency                            |
| `invalid_webhook_url`            | invalid url format                          |
| `application_not_authorized`     | application not authorized                  |
| `user_not_active`                | user account is not active                  |
| `user_balance_not_found`         | user balance not found                      |
| `merchant_not_active`            | merchant account is not active              |
| `merchant_balance_not_found`     | merchant balance not found                  |
| `invalid_amount`                 | invalid amount                              |
| `insufficient_balance`           | insufficient balance                        |
| `provider_not_found`             | payment provider not found                  |
| `psp_currency_balance_not_found` | payment provider currency balance not found |
| `invalid_provider_name`          | invalid payment provider name               |
| `psp_error`                      | payment provider error                      |
| `reference_already_used`         | a transaction with the reference id exists  |
| `internal_server_error`          | internal server error                       |