​
Overview

The OneKhusa disbursement webhooks provide an easy way for merchant back-office systems to receive real-time notifications whenever batch funds transfer to the beneficiaries succeeded or failed. Instead of manually checking for disbursement status, webhooks automatically notify your system as soon as a batch disbursement event occurs.
Important: Do not trust any webhook notifications received, your system is required to verify prior to processing to avoid unauthorised notifications being processed.

​
Webhook Configuration

​
Step 1: Access OneKhusa Portal

  1. Login at https://app.onekhusa.com
  2. Go to Developers → Webhooks
  3. Open Webhook Configuration interface

​
Step 2: Configure Your Webhook

Configure your webhook endpoint with the required information below.

​
Required Information

Request Headers
Header NameDescriptionExample
X-OneKhusa-Webhook-EventThe request should include this header indicating the event typebatch.received, batch.failed
X-OneKhusa-Webhook-SignatureA secret signature used to verify the authenticity of webhook notificationsa1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
Webhook signatures should not be shared with unauthorised users.

​
Webhook Events

​
1. Batch Received Event

​
event_code
string
default:"batch.received"
Event Code: batch.received
  • Description: Triggered when a batch is successfully received and queued for processing. You still receive this notification even when some transactions fail - you only receive batch.failed when all transactions fail
  • When Sent: Immediately after batch validation and creation

​
2. Batch Failed Event

​
event_code
string
default:"batch.failed"
Event Code: batch.failed
  • Description: Triggered when a batch fails validation or processing. The response may include metadata depending on the specific failure type and available information.
  • When Sent: Immediately when batch processing fails

​
3. Payout Success Event

​
event_code
string
default:"payout.success"
Event Code: payout.success
  • Description: Triggered when batch disbursement transactions are successfully completed
  • When Sent: After 10 transactions in a batch are processed

​
4. Failed Payout Event

​
event_code
string
default:"payout.failed"
Event Code: payout.failed
  • Description: Triggered when batch disbursement transactions fail
  • When Sent: After 10 transactions in a batch are processed

​
5. Reversed Payout Event

​
event_code
string
default:"payout.reversed"
Event Code: payout.reversed
  • Description: Triggered when batch disbursement transactions are reversed
  • When Sent: After 10 transactions in a batch are processed

​
Batch Disbursement Payload Structure

Example JSON payloads for different disbursement transaction statuses: 
[
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "ATSY27181",
    "beneficiaryAccountNumber": "1234567890",
    "beneficiaryAccountName": "John Doe",
    "transactionReferenceNumber": "251105PCDRLL",
    "transactionAmount": 1000.50,
    "transactionFee": 10.00,
    "transactionDate": "2024-01-15T09:00:00Z",
    "processedDate": "2024-01-15T10:30:00Z",
    "transactionStatusCode": "S",
    "responseCode": "S100",
    "transactionCode": "MBA",
    "connectorId": 213346
  },
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "BTSY27182",
    "beneficiaryAccountNumber": "0987654321",
    "beneficiaryAccountName": "Jane Smith",
    "transactionReferenceNumber": "TXN-REF-12345",
    "transactionAmount": 2500.75,
    "transactionFee": 15.00,
    "transactionDate": "2024-01-15T09:05:00Z",
    "processedDate": "2024-01-15T10:35:00Z",
    "transactionStatusCode": "S",
    "responseCode": "S100",
    "transactionCode": "MMW",
    "connectorId": 213346
  }
]

​
Single Disbursement Payload Structure

Example JSON payloads for different disbursement transaction statuses: 
{
  "sourceAccountNumber": "9876543210",
  "sourceReferenceNumber": "ZESY27181",
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "transactionReferenceNumber": "251105812UIK",
  "transactionAmount": 1000.50,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "S",
  "responseCode": "S100",
  "transactionCode": "MBA",
  "connectorId": 223758
}

​
Field Descriptions

FieldTypeDescriptionExample
SourceAccountNumberstringThe account number from which the disbursement originates85231947
SourceReferenceNumberstringThis is a unique identifier from the source systemQKAHXD200923
BeneficiaryAccountNumberstringThe account number of the recipient1111203344
TransactionReferenceNumberstringA unique transaction reference generated by the system251005TYHKOPL
TransactionAmountdecimalThe monetary value of the disbursement transaction15000.00
TransactionFeedecimalThe fee charged for processing the transaction1000.00
TransactionDatedatetimeThe date and time when the transaction was initiated2025-10-10T09:00:00Z
ProcessedDatedatetimeThe date and time when the transaction was completed2025-10-10T09:11:10Z
TransactionStatusCodestringThe status of the transaction (S = Success, F = Failed, R = Reversed)S
BeneficiaryAccountNamestringThe name registered on the beneficiary’s accountJohn Doe
ResponseCodestringThe code set after the disbursement transaction is processed. Refer to Transaction Responses for more details.S000
TransactionCodestringAn internal transaction code used for classification or processing. For disbursements, this will be MBA (Merchant To Account) or MMW (Merchant To Mobile Wallet). Refer to Transaction Types for more details.MBA, MMW
ConnectorIdintegerThe unique number representing the institution (bank/MNO) used for the disbursement transaction213346