Deposits (C2B) - DCash API Documentation

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

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:

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

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

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 Payment Providers Check Transaction Status

​Endpoint

​Description

​Headers

​Body Parameters

​Response

​Example Request

​Example Response

​Error Codes

Endpoint

Description

Headers

Body Parameters

Response

Example Request

Example Response

Error Codes