Deposits (C2B)

Deposits (C2B)

curl --request POST \
  --url https://sandbox.dcash.africa/merchants/transactions/c2b \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "reference_id": "<string>",
  "description": "<string>",
  "payment_provider": "<string>",
  "amount": 123,
  "currency": "<string>",
  "webhook_url": "<string>"
}
'

import requests

url = "https://sandbox.dcash.africa/merchants/transactions/c2b"

payload = {
    "reference_id": "<string>",
    "description": "<string>",
    "payment_provider": "<string>",
    "amount": 123,
    "currency": "<string>",
    "webhook_url": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference_id: '<string>',
    description: '<string>',
    payment_provider: '<string>',
    amount: 123,
    currency: '<string>',
    webhook_url: '<string>'
  })
};

fetch('https://sandbox.dcash.africa/merchants/transactions/c2b', 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/c2b",
  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>',
    'amount' => 123,
    'currency' => '<string>',
    'webhook_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "x-api-key: <x-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/c2b"

	payload := strings.NewReader("{\n  \"reference_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payment_provider\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"webhook_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Authorization", "<authorization>")
	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/c2b")
  .header("x-api-key", "<x-api-key>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reference_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payment_provider\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"webhook_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.dcash.africa/merchants/transactions/c2b")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reference_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payment_provider\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"webhook_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "transaction_id": "<string>",
  "reference_id": "<string>",
  "transaction_status": "<string>",
  "amount": 123,
  "currency": "<string>"
}

POST

merchants

transactions

c2b

Deposits (C2B)

curl --request POST \
  --url https://sandbox.dcash.africa/merchants/transactions/c2b \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "reference_id": "<string>",
  "description": "<string>",
  "payment_provider": "<string>",
  "amount": 123,
  "currency": "<string>",
  "webhook_url": "<string>"
}
'

import requests

url = "https://sandbox.dcash.africa/merchants/transactions/c2b"

payload = {
    "reference_id": "<string>",
    "description": "<string>",
    "payment_provider": "<string>",
    "amount": 123,
    "currency": "<string>",
    "webhook_url": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference_id: '<string>',
    description: '<string>',
    payment_provider: '<string>',
    amount: 123,
    currency: '<string>',
    webhook_url: '<string>'
  })
};

fetch('https://sandbox.dcash.africa/merchants/transactions/c2b', 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/c2b",
  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>',
    'amount' => 123,
    'currency' => '<string>',
    'webhook_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "x-api-key: <x-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/c2b"

	payload := strings.NewReader("{\n  \"reference_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payment_provider\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"webhook_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Authorization", "<authorization>")
	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/c2b")
  .header("x-api-key", "<x-api-key>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reference_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payment_provider\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"webhook_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.dcash.africa/merchants/transactions/c2b")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reference_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payment_provider\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"webhook_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "transaction_id": "<string>",
  "reference_id": "<string>",
  "transaction_status": "<string>",
  "amount": 123,
  "currency": "<string>"
}

Endpoint

POST /merchants/transactions/c2b

Description

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

Balance Check

System checks if the user has sufficient balance for the requested payment amount

Sufficient Balance

If balance is sufficient, the transfer is processed immediately and response is returned

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

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

Headers

string

required

Merchant API key for authentication

string

required

Bearer token of the authenticated userFormat: Bearer {token}

Body Parameters

string

required

Merchant-provided unique identifier for tracking

string

Description of the deposit transaction

string

Payment provider to use (e.g., “mpesa”, “airtel”)Must be one of the providers returned by the Get Payment Providers endpoint

number

required

Amount to deposit

string

required

Currency code (e.g., “USD”)

string

URL to receive transaction completion notification

Response

string

Unique identifier for the transaction

string

Merchant-provided reference ID (if provided)

string

Current status of the transaction (e.g., “pending”)

number

Amount of the transaction

string

Currency code

Example Request

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

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);

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
$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);
?>

Example Response

200 OK

{
  "transaction_id": "skjr3",
  "reference_id": "abcd",
  "transaction_status": "pending",
  "amount": 123,
  "currency": "USD"
}

When the transaction completes, you’ll receive a webhook notification with the final transaction status and additional details.

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

Get Started

User Management

Transactions

Webhooks

Endpoint

Description

Headers

Body Parameters

Response

Example Request

Example Response

Error Codes

​Endpoint

​Description

​Headers

​Body Parameters

​Response

​Example Request

​Example Response

​Error Codes

Endpoint

Description

Headers

Body Parameters

Response

Example Request

Example Response

Error Codes