Skip to main content
POST
/
merchants
/
transactions
/
b2c
Withdrawals (B2C)
curl --request POST \
  --url https://sandbox.dcash.africa/merchants/transactions/b2c \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "reference_id": "<string>",
  "description": "<string>",
  "payment_provider": "<string>",
  "email": "<string>",
  "amount": 123,
  "currency": "<string>"
}
'
{
  "transaction_id": "<string>",
  "reference_id": "<string>",
  "transaction_status": "<string>",
  "amount": 123,
  "currency": "<string>",
  "date_completed": 123
}

​
Endpoint

POST /merchants/transactions/b2c

​
Description

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

Transfer to DCash

Funds are transferred from your merchant account to the user’s DCash account
2

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
3

Complete

Transaction completes and response is returned

​
Body Parameters

​
reference_id
string
Merchant-provided unique identifier for the transaction
​
description
string
Brief description of the withdrawal
​
payment_provider
string
Provider to process the withdrawal (e.g., “mpesa”, “airtel”)
​
email
string
required
User’s email address
​
amount
number
required
Amount to withdraw
​
currency
string
required
Currency code (e.g., “USD”)

​
Response

​
transaction_id
string
Unique identifier for the transaction
​
reference_id
string
Merchant-provided reference ID (if provided)
​
transaction_status
string
Status of the transaction (e.g., “completed”)
​
amount
number
Amount withdrawn
​
currency
string
Currency code
​
date_completed
number
Timestamp of completion (format: YYYYMMDDHHMMSS)

​
Example Request

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"
  }'

​
Example Response

{
  "transaction_id": "skjr7",
  "reference_id": "abcd",
  "transaction_status": "completed",
  "amount": 10,
  "currency": "USD",
  "date_completed": 20250401125109
}

​
Important Notes

Ensure you have sufficient balance in your merchant account before initiating withdrawals.
Unlike deposits, withdrawals typically complete synchronously and return the full transaction details in the immediate response.

​
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

CodeMessage
missing_api_keyplease provide an api key
invalid_api_keyapi key does not exist
invalid_emailinvalid email address
user_not_founduser not found
invalid_currencyinvalid currency
user_not_activeuser not active
user_balance_not_founduser balance not found
merchant_not_activemerchant not active
merchant_balance_not_foundmerchant balance not found
invalid_amountinvalid amount
insufficient_balanceinsufficient balance
reference_already_useda transaction with the reference id exists
internal_server_errorinternal server error