> ## 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.

# Withdrawals (B2C)

> Initiate a business-to-customer withdrawal transaction

## Endpoint

```
POST /merchants/transactions/b2c
```

## Description

Initiates a fund transfer to the user's DCash account. The transaction flow works as follows:

<Steps>
  <Step title="Transfer to DCash">
    Funds are transferred from your merchant account to the user's DCash account
  </Step>

  <Step title="Withdraw to Provider">
    If payment provider is provided in the request, funds are withdrawn from the user’s DCash account and sent to the specified payment provider. Otherwise, the funds remain in the user’s DCash account
  </Step>

  <Step title="Complete">
    Transaction completes and response is returned
  </Step>
</Steps>

## Body Parameters

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

<ParamField body="description" type="string">
  Brief description of the withdrawal
</ParamField>

<ParamField body="payment_provider" type="string">
  Provider to process the withdrawal (e.g., "mpesa", "airtel")
</ParamField>

<ParamField body="email" type="string" required>
  User's email address
</ParamField>

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

<ParamField body="currency" type="string" required>
  Currency code (e.g., "USD")
</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">
  Status of the transaction (e.g., "completed")
</ResponseField>

<ResponseField name="amount" type="number">
  Amount withdrawn
</ResponseField>

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

<ResponseField name="date_completed" type="number">
  Timestamp of completion (format: YYYYMMDDHHMMSS)
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://sandbox.dcash.africa/merchants/transactions/b2c \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_MERCHANT_API_KEY' \
    --data '{
      "reference_id": "abcd",
      "description": "Test withdrawal",
      "payment_provider": "mpesa",
      "email": "test.user@dcash.africa",
      "amount": 10,
      "currency": "USD"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://sandbox.dcash.africa/merchants/transactions/b2c', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_MERCHANT_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference_id: 'abcd',
      description: 'Test withdrawal',
      payment_provider: 'mpesa',
      email: 'peter.kayere@dcash.africa',
      amount: 10,
      currency: 'USD'
    })
  });

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

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

  url = "https://sandbox.dcash.africa/merchants/transactions/b2c"
  headers = {
      "x-api-key": "YOUR_MERCHANT_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "reference_id": "abcd",
      "description": "Test withdrawal",
      "payment_provider": "mpesa",
      "email": "test.user@dcash.africa",
      "amount": 10,
      "currency": "USD"
  }

  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/b2c");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "x-api-key: YOUR_MERCHANT_API_KEY",
      "Content-Type: application/json"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      "reference_id" => "abcd",
      "description" => "Test withdrawal",
      "payment_provider" => "mpesa",
      "email" => "test.user@dcash.africa",
      "amount" => 10,
      "currency" => "USD"
  ]));

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

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

## Example Response

<CodeGroup>
  ```json Response theme={null}
  {
    "transaction_id": "skjr7",
    "reference_id": "abcd",
    "transaction_status": "completed",
    "amount": 10,
    "currency": "USD",
    "date_completed": 20250401125109
  }
  ```
</CodeGroup>

## Important Notes

<Warning>
  Ensure you have sufficient balance in your merchant account before initiating withdrawals.
</Warning>

<Info>
  Unlike deposits, withdrawals typically complete synchronously and return the full transaction details in the immediate response.
</Info>

## Use Cases

Common scenarios for B2C withdrawals:

* **Payouts**: Sending earnings or rewards to users
* **Refunds**: Processing refund requests
* **Cashouts**: Allowing users to withdraw their balance
* **Disbursements**: Distributing funds to multiple recipients

## Error Codes

| Code                         | Message                                    |
| ---------------------------- | ------------------------------------------ |
| `missing_api_key`            | please provide an api key                  |
| `invalid_api_key`            | api key does not exist                     |
| `invalid_email`              | invalid email address                      |
| `user_not_found`             | user not found                             |
| `invalid_currency`           | invalid currency                           |
| `user_not_active`            | user not active                            |
| `user_balance_not_found`     | user balance not found                     |
| `merchant_not_active`        | merchant not active                        |
| `merchant_balance_not_found` | merchant balance not found                 |
| `invalid_amount`             | invalid amount                             |
| `insufficient_balance`       | insufficient balance                       |
| `reference_already_used`     | a transaction with the reference id exists |
| `internal_server_error`      | internal server error                      |