Payout Transaction

Important: Do not trust any webhook notifications received, your system is required to verify prior to processing to avoid unauthorised notifications being processed.

1. Successful Payout (`payout.success`)

The payout.success event is dispatched immediately after funds are successfully transferred from your merchant account and credited to the beneficiary’s mobile money wallet (e.g., Airtel Money, TNM Mpamba) or commercial bank account. This event confirms final settlement, allowing your backend to safely update transaction accounts and confirm payout completion.

HTTP Request Example

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: payout.success
X-OneKhusa-Webhook-Signature: 9b71d2fe4a39281a8b329487c53d10a972c7247853b01938b8d901f421f1e298

JSON Payload

{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812UIK",
  "sourceReferenceNumber": "SRC4K8L2M9Q1Z",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MBA",
  "transactionAmount": 1000.00,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "S",
  "responseCode": "S100",
  "connectorId": 220400
}

2. Failed Payout (`payout.failed`)

The payout.failed event is emitted when an individual payout request fails during execution (e.g., due to an invalid/inactive beneficiary account, network timeout, or carrier rejection). When this occurs, any held principal funds and associated transaction fees are automatically credited back to your OneKhusa merchant account balance, requiring your backend to mark the payout attempt as failed.

HTTP Request Example

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: payout.failed
X-OneKhusa-Webhook-Signature: 7c82a1b94e310d2938ab4710293e847192039b821a82301938b8d901f421f1e2

JSON Payload

{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812HMM",
  "sourceReferenceNumber": "671DS8L2M9Q1Z",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MMW",
  "transactionAmount": 1000.00,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "F",
  "responseCode": "E999",
  "connectorId": 220400
}

3. Payout Reversal (`payout.reversed`)

The payout.reversed event is emitted if a previously settled payout transaction must be rolled back due to a downstream bank reversal, carrier settlement error, or compliance adjustment. Receiving this event indicates that the transaction state has been converted to Reversed, requiring your backend system to adjust system accounts accordingly.

HTTP Request Example

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: payout.reversed
X-OneKhusa-Webhook-Signature: d3840e2f5b610c2838491823abf10928aef49102938471b028471920d39b821a

JSON Payload

{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812HMM",
  "sourceReferenceNumber": "671DS8L2M9Q1Z",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MMW",
  "transactionAmount": 1000.00,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "R",
  "responseCode": "S100",
  "connectorId": 220400
}

Payload Field Reference

The table below details all attributes present within single disbursement webhook notification payloads:

Field	Type	Description	Example
`sourceAccountNumber`	string	The account number from which the disbursement originates	`85231947`
`sourceReferenceNumber`	string	A unique identifier from the source system	`QKAHXD200923`
`beneficiaryAccountNumber`	string	The account number of the recipient	`1111203344`
`beneficiaryInstitution`	string	The name of the institution where the beneficiary’s account is held	`National Bank of Malawi`
`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`
`transactionDescription`	string	A brief description of the transaction	`Salary Payment for September`
`transactionDate`	datetime	The date and time when the transaction was initiated (ISO 8601)	`2025-10-10T09:00:00Z`
`processedDate`	datetime	The date and time when the transaction was completed (ISO 8601)	`2025-10-10T09:11:10Z`
`transactionStatusCode`	string	The status of the transaction (S = Success, F = Failed, R = Reversed)	`S`
`beneficiaryAccountName`	string	The name registered on the beneficiary’s account	`John Doe`
`responseCode`	string	The code set after the disbursement transaction is processed. Refer to Transaction Responses for more details.	`S000`
`transactionCode`	string	An 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`
`connectorId`	integer	The unique number representing the institution (bank/MNO) used for the disbursement transaction	`220400`

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

1. Successful Payout (`payout.success`)

HTTP Request Example

JSON Payload

2. Failed Payout (`payout.failed`)

HTTP Request Example

JSON Payload

3. Payout Reversal (`payout.reversed`)

HTTP Request Example

JSON Payload

Payload Field Reference

​1. Successful Payout (payout.success)

​HTTP Request Example

​JSON Payload

​2. Failed Payout (payout.failed)

​HTTP Request Example

​JSON Payload

​3. Payout Reversal (payout.reversed)

​HTTP Request Example

​JSON Payload

​Payload Field Reference

1. Successful Payout (`payout.success`)

HTTP Request Example

JSON Payload

2. Failed Payout (`payout.failed`)

HTTP Request Example

JSON Payload

3. Payout Reversal (`payout.reversed`)

HTTP Request Example

JSON Payload

Payload Field Reference