Webhook Events

Webhook notifications are how the OneKhusa platform informs your system about transaction events in real-time. Each webhook contains an event code that identifies the specific type of occurrence, allowing you to automate your backend processes accordingly.

Callback URL Requirements

Before setting up webhooks, ensure your receiving endpoint (callback URL) meets the following technical requirements:

Ensure your webhook endpoint meets the following requirements:

HTTPS Protocol: The URL must use HTTPS for secure communication
Public Accessibility: The URL must be publicly accessible and reachable from the internet
POST Request Support: The endpoint must accept HTTP POST requests with JSON payloads
Response Confirmation: Your server must respond with a HTTP 200 OK status code with a string payload such as acknowledged to confirm successful receipt of the webhook. Failure to do so will result in retries..

Webhook Configuration Through OneKhusa Portal

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

Collection Events

These events relate to the collection of funds from your customers.

Event Code	Event Name	Event Description
`payment.success`	Successful Collection	Triggered when a payment collection transaction has been completed successfully. This indicates that funds have been successfully collected from the payer and credited to your merchant account.
`payment.reversed`	Reversed Collection	Triggered when a previously successful payment collection has been reversed due to a dispute or other reversal request. The collected funds are returned to the payer’s account.
`payrequest.success`	Successful request-to-pay transaction	Triggered when a request-to-pay transaction has been processed successfully. This indicates that funds have been successfully collected from the payer and credited to your merchant account.
`payrequest.reversed`	Reversed request-to-pay transaction	Triggered when a previously successful request-to-pay transaction has been reversed due to various reasons. The collected funds are returned to the payer’s account.

Batch Disbursement Events

These events relate to the processing of batch files containing multiple disbursements.

Event Code	Event Name	Event Description
`batch.received`	Batch Disbursements Received	Triggered when a batch disbursement file has been successfully received and accepted by the system. This confirms the file passed initial validation and has been queued for processing.
`batch.failed`	Batch Disbursements Failed	Triggered when the entire batch cannot be processed due to system errors, insufficient funds, or other critical issues. Individual transactions within the batch are marked as failed, and funds are refunded to your merchant account.
`batch.payout.success`	Successful Batch Disbursements	Triggered when the batch disbursement transactions have been completed successfully. This indicates that funds have been successfully transferred from your merchant account to the beneficiary accounts or wallets.
`batch.payout.failed`	Failed Batch Disbursements	Triggered when the batch disbursement transactions have failed. This can occur due to invalid beneficiary details, insufficient merchant balance, or gateway errors. The total transaction amount is automatically refunded to your merchant account.
`batch.payout.reversed`	Reversed Batch Disbursements	Triggered when a previously successful disbursement has been reversed due to beneficiary disputes or compliance issues. The funds are returned to your merchant account.

Single Disbursement Events

These events relate to the processing of a funds transfer transaction to one beneficiary.

Event Code	Event Name	Event Description
`payout.success`	Successful Disbursement	Triggered when a disbursement (payout) transaction has been completed successfully. This indicates that funds have been successfully transferred from your merchant account to the beneficiary’s account.
`payout.failed`	Failed Disbursement	Triggered when a disbursement transaction has failed. This can occur due to invalid beneficiary details, insufficient merchant balance, or gateway errors. The transaction amount is automatically refunded to your merchant account.
`payout.reversed`	Reversed Disbursement	Triggered when a previously successful disbursement has been reversed due to beneficiary disputes or compliance issues. The funds are returned to your merchant account.

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

Callback URL Requirements

Webhook Configuration Through OneKhusa Portal

Collection Events

Batch Disbursement Events

Single Disbursement Events

​Callback URL Requirements

​Webhook Configuration Through OneKhusa Portal

​Collection Events

​Batch Disbursement Events

​Single Disbursement Events

Callback URL Requirements

Webhook Configuration Through OneKhusa Portal

Collection Events

Batch Disbursement Events

Single Disbursement Events