Batch Funds Transfer

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 Batch Payout (`batch.payout.success`)

The batch.payout.success event is dispatched immediately a chunk/group of up-to-10 transactions within the batch completed successfully and funds credited to beneficiary’s mobile wallets and bank accounts. This event confirms final funds settlement, allowing your backend to safely update transaction accounts and confirm chunk payout completion.

HTTP Request Example

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

JSON Payload

[
  {
    "sourceAccountNumber": "98743210",
    "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": "98743210",
    "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
  }
]

2. Failed Batch Payout (`batch.payout.failed`)

The batch.payout.failed event is emitted immediately a chunk/group of up-to-10 transactions within the batch fails (e.g., invalid account, destination network down). 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 batch 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: batch.payout.failed
X-OneKhusa-Webhook-Signature: 7c82a1b94e310d2938ab4710293e847192039b821a82301938b8d901f421f1e2

JSON Payload

[
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "WTSY27181",
    "beneficiaryAccountNumber": "1234567890",
    "beneficiaryAccountName": "John Doe",
    "transactionReferenceNumber": "TXN-REF-67890",
    "transactionAmount": 1000.50,
    "transactionFee": 10.00,
    "transactionDate": "2024-01-15T09:00:00Z",
    "processedDate": "2024-01-15T10:30:00Z",
    "transactionStatusCode": "F",
    "responseCode": "E233",
    "transactionCode": "MBA",
    "connectorId": 224368
  },
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "BTSY27ER3",
    "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": "F",
    "responseCode": "E228",
    "transactionCode": "MMW",
    "connectorId": 224368
  }
]

3. Batch Payout Reversal (`batch.payout.reversed`)

The batch.payout.reversed event is emitted if the previously settled batch payout transactions must be rolled back due to a downstream bank reversal, carrier settlement error, or compliance adjustment. Receiving this event indicates that the batch transactions’ 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: batch.payout.reversed
X-OneKhusa-Webhook-Signature: d3840e2f5b610c2838491823abf10928aef49102938471b028471920d39b821a

JSON Payload

[
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "WFKY27181",
    "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": "R",
    "responseCode": "S100",
    "transactionCode": "MBA",
    "connectorId": 213346
  },
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "ERSY27956",
    "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": "R",
    "responseCode": "S100",
    "transactionCode": "MBA",
    "connectorId": 213346
  }
]

Payload Field Reference

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

Field	Type	Description	Example
`sourceAccountNumber`	string	The account number from which the disbursement originates	`98743210`
`sourceReferenceNumber`	string	A unique identifier from the source system	`ATSY27181`
`beneficiaryAccountNumber`	string	The account number of the recipient	`1234567890`
`beneficiaryAccountName`	string	The name registered on the beneficiary’s account	`John Doe`
`transactionReferenceNumber`	string	A unique transaction reference generated by the system	`251105PCDRLL`
`transactionAmount`	decimal	The monetary value of the disbursement transaction	`1000.50`
`transactionFee`	decimal	The fee charged for processing the transaction	`10.00`
`transactionDate`	datetime	The date and time when the transaction was initiated (ISO 8601)	`2024-01-15T09:00:00Z`
`processedDate`	datetime	The date and time when the transaction was completed (ISO 8601)	`2024-01-15T10:30:00Z`
`transactionStatusCode`	string	The status of the transaction (S = Success, F = Failed, R = Reversed)	`S`
`responseCode`	string	The code set after the disbursement transaction is processed. Refer to Transaction Responses for more details.	`S100`
`transactionCode`	string	An internal transaction code used for classification. For disbursements, this will be `MBA` (Merchant To Account) or `MMW` (Merchant To Mobile Wallet).	`MBA`
`connectorId`	integer	The unique number representing the institution (bank/MNO) used for the disbursement transaction	`213346`

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

1. Successful Batch Payout (`batch.payout.success`)

HTTP Request Example

JSON Payload

2. Failed Batch Payout (`batch.payout.failed`)

HTTP Request Example

JSON Payload

3. Batch Payout Reversal (`batch.payout.reversed`)

HTTP Request Example

JSON Payload

Payload Field Reference

​1. Successful Batch Payout (batch.payout.success)

​HTTP Request Example

​JSON Payload

​2. Failed Batch Payout (batch.payout.failed)

​HTTP Request Example

​JSON Payload

​3. Batch Payout Reversal (batch.payout.reversed)

​HTTP Request Example

​JSON Payload

​Payload Field Reference

1. Successful Batch Payout (`batch.payout.success`)

HTTP Request Example

JSON Payload

2. Failed Batch Payout (`batch.payout.failed`)

HTTP Request Example

JSON Payload

3. Batch Payout Reversal (`batch.payout.reversed`)

HTTP Request Example

JSON Payload

Payload Field Reference