Skip to main content
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>"
}
'
{
  "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:
1

Balance Check

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

Sufficient Balance

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

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
4

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

​
x-api-key
string
required
Merchant API key for authentication
​
Authorization
string
required
Bearer token of the authenticated userFormat: Bearer {token}

​
Body Parameters

​
reference_id
string
required
Merchant-provided unique identifier for tracking
​
description
string
Description of the deposit transaction
​
payment_provider
string
Payment provider to use (e.g., “mpesa”, “airtel”)Must be one of the providers returned by the Get Payment Providers endpoint
​
amount
number
required
Amount to deposit
​
currency
string
required
Currency code (e.g., “USD”)
​
webhook_url
string
URL to receive transaction completion notification

​
Response

​
transaction_id
string
Unique identifier for the transaction
​
reference_id
string
Merchant-provided reference ID (if provided)
​
transaction_status
string
Current status of the transaction (e.g., “pending”)
​
amount
number
Amount of the transaction
​
currency
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"
  }'

​
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

CodeMessage
missing_api_keyplease provide an api key
invalid_api_keyapi key does not exist
authorization_token_not_foundplease provide a bearer authorization token
invalid_currencyinvalid currency
invalid_webhook_urlinvalid url format
application_not_authorizedapplication not authorized
user_not_activeuser account is not active
user_balance_not_founduser balance not found
merchant_not_activemerchant account is not active
merchant_balance_not_foundmerchant balance not found
invalid_amountinvalid amount
insufficient_balanceinsufficient balance
provider_not_foundpayment provider not found
psp_currency_balance_not_foundpayment provider currency balance not found
invalid_provider_nameinvalid payment provider name
psp_errorpayment provider error
reference_already_useda transaction with the reference id exists
internal_server_errorinternal server error