Skip to main content

​
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:
  1. Per-request: Include the webhook_url parameter in your API request
  2. 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
}
​
transaction_id
string
Unique identifier for the transaction
​
reference_id
string
Merchant-provided reference ID from the original request
​
transaction_status
string
Status of the transaction (e.g., “completed”, “failed”)
​
user_email
string
Email of the user who made the deposit
​
amount
number
Amount deposited
​
currency
string
Currency code (e.g., “USD”)
​
description
string
Description of the transaction
​
date_completed
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:
  1. Respond quickly: Return a 200 OK response within 5 seconds
  2. Process asynchronously: Handle the webhook data in a background job if needed
  3. 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:
  1. Webhook testing tools: Use services like webhook.site or ngrok to create temporary public URLs
  2. Sandbox environment: All sandbox transactions trigger webhooks to help you test your integration

​
Transaction Statuses

Webhook notifications may include these transaction statuses:
StatusDescription
completedTransaction completed successfully
failedTransaction failed
pendingTransaction 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:
  1. Check that your webhook URL is correctly configured
  2. Verify your endpoint is publicly accessible
  3. Use the Check Transaction Status endpoint to get the transaction result
  4. 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

Always use HTTPS webhook URLs to ensure secure transmission of transaction data.
Always verify that webhook requests come from DCash’s server IP: 41.209.57.197
Verify that the transaction details match your records before processing.
Keep logs of all webhook deliveries for debugging and audit purposes.
If processing fails, return 200 OK to prevent retries, then handle the error separately.
Set up alerts for failed webhook deliveries to catch issues quickly.