Webhooks

Overview

Webhooks allow you to receive real-time notifications when transaction events occur. Instead of polling for transaction status updates, DCash will send HTTP POST requests to your configured webhook URL when transactions complete.

Configuring Webhooks

You can configure webhook URLs in two ways:

Per-request: Include the webhook_url parameter in your API request
Default URL: Set a default webhook URL in your merchant portal

Per-request webhook URLs take precedence over the default URL configured in your merchant portal.

Webhook Security

To ensure webhook requests originated from DCash:

Verify the source IP address: All webhooks are sent from 41.209.57.197
Use HTTPS endpoints: Ensure encrypted transmission of transaction data
Validate transaction data: Cross-check the transaction details against your records

Webhook Payload Structure

Deposit (C2B) Webhooks

When a C2B deposit transaction completes, your webhook receives:

{
  "transaction_id": "skjr3",
  "reference_id": "abcd",
  "transaction_status": "completed",
  "user_email": "test.user@dcash.africa",
  "amount": 10,
  "currency": "USD",
  "description": "Test Deposit",
  "date_completed": 20241214125109
}

string

Unique identifier for the transaction

string

Merchant-provided reference ID from the original request

string

Status of the transaction (e.g., “completed”, “failed”)

string

Email of the user who made the deposit

number

Amount deposited

string

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

string

Description of the transaction

number

Timestamp of completion (format: YYYYMMDDHHMMSS)

Withdrawal (B2C) Webhooks

When a B2C withdrawal transaction completes, your webhook receives:

{
  "transaction_id": "skjr7",
  "reference_id": "abcd",
  "transaction_status": "completed",
  "user_email": "test.user@dcash.africa",
  "amount": 10,
  "currency": "USD",
  "description": "Test withdrawal",
  "date_completed": 20250401125109
}

The payload structure is identical to deposits, containing the same fields.

Responding to Webhooks

Your webhook endpoint should:

Respond quickly: Return a 200 OK response within 5 seconds
Process asynchronously: Handle the webhook data in a background job if needed
Be idempotent: Handle duplicate webhook deliveries gracefully using transaction_id

Example Webhook Handler

app.post('/webhook/dcash', async (req, res) => {
  // Verify the request comes from DCash
  const clientIp = req.ip || req.connection.remoteAddress;
  if (clientIp !== '41.209.57.197') {
    return res.status(403).send('Forbidden');
  }

  // Respond immediately
  res.status(200).send('OK');

  // Process asynchronously
  const { transaction_id, transaction_status, amount } = req.body;

  // Check if already processed (idempotency)
  if (await isProcessed(transaction_id)) {
    return;
  }

  // Handle the webhook
  if (transaction_status === 'completed') {
    await processSuccessfulTransaction(req.body);
  } else if (transaction_status === 'failed') {
    await processFailedTransaction(req.body);
  }

  // Mark as processed
  await markAsProcessed(transaction_id);
});

Webhook Retry Logic

If your endpoint doesn’t respond with a 200 OK status:

DCash will retry the webhook up to 3 times
Retries occur at increasing intervals (5 min, 30 min, 2 hours)
After 3 failed attempts, you’ll need to use the Check Transaction Status endpoint

If webhooks consistently fail, ensure your endpoint is accessible, responds quickly, and returns a 200 status code.

Testing Webhooks

During development, you can test webhooks using:

Webhook testing tools: Use services like webhook.site or ngrok to create temporary public URLs
Sandbox environment: All sandbox transactions trigger webhooks to help you test your integration

Transaction Statuses

Webhook notifications may include these transaction statuses:

Status	Description
`completed`	Transaction completed successfully
`failed`	Transaction failed
`pending`	Transaction is still processing

When you receive a “completed” status, the funds have been successfully transferred.

Troubleshooting

Webhook not received

If you don’t receive a webhook notification:

Check that your webhook URL is correctly configured
Verify your endpoint is publicly accessible
Use the Check Transaction Status endpoint to get the transaction result
Check your server logs for incoming requests

Multiple webhook deliveries

Webhooks may be delivered more than once. Implement idempotency using the transaction_id to prevent duplicate processing.

Best Practices

Use HTTPS endpoints

Always use HTTPS webhook URLs to ensure secure transmission of transaction data.

Verify source IP address

Always verify that webhook requests come from DCash’s server IP: 41.209.57.197

Validate webhook data

Verify that the transaction details match your records before processing.

Log all webhooks

Keep logs of all webhook deliveries for debugging and audit purposes.

Handle errors gracefully

If processing fails, return 200 OK to prevent retries, then handle the error separately.

Monitor webhook health

Set up alerts for failed webhook deliveries to catch issues quickly.

Get Started

User Management

Transactions

Webhooks

Overview

Configuring Webhooks

Webhook Security

Webhook Payload Structure

Deposit (C2B) Webhooks

Withdrawal (B2C) Webhooks

Responding to Webhooks

Webhook Retry Logic

Testing Webhooks

Transaction Statuses

Troubleshooting

Webhook not received

Multiple webhook deliveries

Best Practices

​Overview

​Configuring Webhooks

​Webhook Security

​Webhook Payload Structure

​Deposit (C2B) Webhooks

​Withdrawal (B2C) Webhooks

​Responding to Webhooks

​Webhook Retry Logic

​Testing Webhooks

​Transaction Statuses

​Troubleshooting

​Webhook not received

​Multiple webhook deliveries

​Best Practices

Overview

Configuring Webhooks

Webhook Security

Webhook Payload Structure

Deposit (C2B) Webhooks

Withdrawal (B2C) Webhooks

Responding to Webhooks

Webhook Retry Logic

Testing Webhooks

Transaction Statuses

Troubleshooting

Webhook not received

Multiple webhook deliveries

Best Practices