​
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

  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

FieldDescriptionExample
Callback URLYour HTTPS endpoint to receive notificationshttps://yourdomain.com/webhooks/khusa
Event TypeWhich events you want to receivebatch.received, batch.failed, payout.success, payout.failed, payout.reversed

​
URL Requirements

Ensure your webhook endpoint meets the following requirements:
  • HTTPS Protocol: The URL must use HTTPS protocol for secure communication
  • Public Accessibility: The URL must be publicly accessible (reachable from the internet)
  • POST Request Support: The endpoint should be able to receive and process HTTP POST requests containing JSON payloads
  • Response Confirmation: It is recommended to respond with HTTP 200 OK to confirm successful receipt of the webhook

​
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

​
Event Types

Event CodeDescriptionWhen Triggered
batch.receivedBatch successfully received and queued for processingImmediately after batch validation and creation
batch.failedBatch failed validation or processingImmediately when batch processing fails
payout.successBatch disbursement transactions completed successfullyAfter 10 transactions in a batch are processed
payout.failedBatch disbursement transactions failedAfter 10 transactions in a batch are processed
payout.reversedBatch disbursement transactions reversedAfter 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"
  }
]

​
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