Disbursement Webhooks

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.

Webhook Configuration

Step 1: Access OneKhusa Portal

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

Step 2: Configure Your Webhook

Configure your webhook endpoint with the required information below.

Required Information

Request Headers

Header Name	Description	Example
X-OneKhusa-Webhook-Event	The request should include this header indicating the event type	`batch.received`, `batch.failed`
X-OneKhusa-Webhook-Signature	A secret signature used to verify the authenticity of webhook notifications	`a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6`

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

Webhook Payload Structure

Example JSON payloads for different disbursement transaction statuses:

Success Payout
Failed Payout
Reversed Payout
Batch Received
Batch Failed

[
  {
    "sourceAccountNumber": "85231947",
    "sourceReferenceNumber": "QKAHXD200923",
    "beneficiaryAccountNumber": "1111203344",
    "transactionReferenceNumber": "250905SLFVXD",
    "transactionAmount": 15000.00,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T09:00:00Z",
    "processedDate": "2025-10-10T09:11:10Z",
    "transactionStatusCode": "S"
  },
  {
    "sourceAccountNumber": "85231947",
    "sourceReferenceNumber": "SRCQ8L2K7B9M",
    "beneficiaryAccountNumber": "1111202099",
    "transactionReferenceNumber": "251014SRTYXB",
    "transactionAmount": 27500.00,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T09:05:00Z",
    "processedDate": "2025-10-10T09:10:45Z",
    "transactionStatusCode": "S"
  }
]

[
  {
    "sourceAccountNumber": "85231947",
    "sourceReferenceNumber": "QKAHXD200923",
    "beneficiaryAccountNumber": "1111203344",
    "transactionReferenceNumber": "251005QRNKPF",
    "transactionAmount": 15000.00,
    "transactionDate": "2025-10-10T09:00:00Z",
    "processedDate": "2025-10-10T09:11:10Z",
    "transactionStatusCode": "F"
  },
  {
    "sourceAccountNumber": "85231947",
    "sourceReferenceNumber": "SRCQ8L2K7B9M",
    "beneficiaryAccountNumber": "1111202099",
    "transactionReferenceNumber": "251014WHTISW",
    "transactionAmount": 27500.00,
    "transactionDate": "2025-10-10T09:05:00Z",
    "processedDate": "2025-10-10T09:10:45Z",
    "transactionStatusCode": "F"
  }
]

[
  {
    "sourceAccountNumber": "85231947",
    "sourceReferenceNumber": "QKAHXD200923",
    "beneficiaryAccountNumber": "1111203344",
    "transactionReferenceNumber": "251005UIKLDH",
    "transactionAmount": 15000.00,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T09:00:00Z",
    "processedDate": "2025-10-10T09:11:10Z",
    "transactionStatusCode": "R"
  },
  {
    "sourceAccountNumber": "85231947",
    "sourceReferenceNumber": "SRCQ8L2K7B9M",
    "beneficiaryAccountNumber": "1111202099",
    "transactionReferenceNumber": "251005TYHKOPL",
    "transactionAmount": 27500.00,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T09:05:00Z",
    "processedDate": "2025-10-10T09:10:45Z",
    "transactionStatusCode": "R"
  }
]

 {
"batchNumber": 20241013001,
"merchantAccountNumber": 35253486,
"numberOfFailedTransactions": 5,
"numberOfSuccessfulTransactions": 145,
"dateReceived": "2024-10-13T10:30:00Z",
"successfulTotalAmount": 150000.00,
"numberOfTransactions": 150,
"dateCaptured": "2024-10-13T10:30:00Z",
"uploadType": "CSV",
"capturerEmailAddress": "johndoe@gmail.com"
}

{
  "merchantAccountNumber": 35253486,
  "isBatchScheduled": false,
  "scheduledDate": null,
  "uploadType": "XLSX",
  "capturerEmailAddress": "johndoe@gmail.com",
  "dateCaptured": "2024-10-13T10:30:00Z",
  "errorMessage": "All transactions failed validation",
  "metaData": {
    "batchNumber": "20241013001",
    "totalAmount": "150000.00",
    "numberOfTransactions": "150",
    "dateOccurred": "2024-10-13T10:30:00Z"
  }
}

Field Descriptions

Field	Type	Description	Example
`SourceAccountNumber`	string	The account number from which the disbursement originates	`85231947`
`SourceReferenceNumber`	string	This is a unique identifier from the source system	`QKAHXD200923`
`BeneficiaryAccountNumber`	string	The account number of the recipient	`1111203344`
`TransactionReferenceNumber`	string	A unique transaction reference generated by the system	`251005TYHKOPL`
`TransactionAmount`	decimal	The monetary value of the disbursement transaction	`15000.00`
`TransactionFee`	decimal	The fee charged for processing the transaction	`1000.00`
`TransactionDate`	datetime	The date and time when the transaction was initiated	`2025-10-10T09:00:00Z`
`ProcessedDate`	datetime	The date and time when the transaction was completed	`2025-10-10T09:11:10Z`
`TransactionStatusCode`	string	The status of the transaction (S = Success, F = Failed, R = Reversed)	`S`

Getting Started

Disbursements

Accept Payments

Merchants

Security

Supporting APIs

Overview

Webhook Configuration

Step 1: Access OneKhusa Portal

Step 2: Configure Your Webhook

Required Information

Request Headers

Webhook Events

1. Batch Received Event

2. Batch Failed Event

3. Payout Success Event

4. Failed Payout Event

5. Reversed Payout Event

Webhook Payload Structure

Field Descriptions

Getting Started

Disbursements

Accept Payments

Merchants

Security

Supporting APIs

​Overview

​Webhook Configuration

​Step 1: Access OneKhusa Portal

​Step 2: Configure Your Webhook

​Required Information

Request Headers

​Webhook Events

​1. Batch Received Event

​2. Batch Failed Event

​3. Payout Success Event

​4. Failed Payout Event

​5. Reversed Payout Event

​Webhook Payload Structure

​Field Descriptions

Overview

Webhook Configuration

Step 1: Access OneKhusa Portal

Step 2: Configure Your Webhook

Required Information

Webhook Events

1. Batch Received Event

2. Batch Failed Event

3. Payout Success Event

4. Failed Payout Event

5. Reversed Payout Event

Webhook Payload Structure

Field Descriptions