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>"
}
'import requests
url = "https://sandbox.dcash.africa/merchants/transactions/b2c"
payload = {
"reference_id": "<string>",
"description": "<string>",
"payment_provider": "<string>",
"email": "<string>",
"amount": 123,
"currency": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reference_id: '<string>',
description: '<string>',
payment_provider: '<string>',
email: '<string>',
amount: 123,
currency: '<string>'
})
};
fetch('https://sandbox.dcash.africa/merchants/transactions/b2c', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.dcash.africa/merchants/transactions/b2c",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reference_id' => '<string>',
'description' => '<string>',
'payment_provider' => '<string>',
'email' => '<string>',
'amount' => 123,
'currency' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.dcash.africa/merchants/transactions/b2c"
payload := strings.NewReader("{\n \"reference_id\": \"<string>\",\n \"description\": \"<string>\",\n \"payment_provider\": \"<string>\",\n \"email\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.dcash.africa/merchants/transactions/b2c")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"reference_id\": \"<string>\",\n \"description\": \"<string>\",\n \"payment_provider\": \"<string>\",\n \"email\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.dcash.africa/merchants/transactions/b2c")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference_id\": \"<string>\",\n \"description\": \"<string>\",\n \"payment_provider\": \"<string>\",\n \"email\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"transaction_id": "<string>",
"reference_id": "<string>",
"transaction_status": "<string>",
"amount": 123,
"currency": "<string>",
"date_completed": 123
}Transactions
Withdrawals (B2C)
Initiate a business-to-customer withdrawal transaction
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>"
}
'import requests
url = "https://sandbox.dcash.africa/merchants/transactions/b2c"
payload = {
"reference_id": "<string>",
"description": "<string>",
"payment_provider": "<string>",
"email": "<string>",
"amount": 123,
"currency": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reference_id: '<string>',
description: '<string>',
payment_provider: '<string>',
email: '<string>',
amount: 123,
currency: '<string>'
})
};
fetch('https://sandbox.dcash.africa/merchants/transactions/b2c', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.dcash.africa/merchants/transactions/b2c",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reference_id' => '<string>',
'description' => '<string>',
'payment_provider' => '<string>',
'email' => '<string>',
'amount' => 123,
'currency' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.dcash.africa/merchants/transactions/b2c"
payload := strings.NewReader("{\n \"reference_id\": \"<string>\",\n \"description\": \"<string>\",\n \"payment_provider\": \"<string>\",\n \"email\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.dcash.africa/merchants/transactions/b2c")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"reference_id\": \"<string>\",\n \"description\": \"<string>\",\n \"payment_provider\": \"<string>\",\n \"email\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.dcash.africa/merchants/transactions/b2c")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference_id\": \"<string>\",\n \"description\": \"<string>\",\n \"payment_provider\": \"<string>\",\n \"email\": \"<string>\",\n \"amount\": 123,\n \"currency\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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
string
Merchant-provided unique identifier for the transaction
string
Brief description of the withdrawal
string
Provider to process the withdrawal (e.g., “mpesa”, “airtel”)
string
required
User’s email address
number
required
Amount to withdraw
string
required
Currency code (e.g., “USD”)
Response
string
Unique identifier for the transaction
string
Merchant-provided reference ID (if provided)
string
Status of the transaction (e.g., “completed”)
number
Amount withdrawn
string
Currency code
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"
}'
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);
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
$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);
?>
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
| 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 |