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 to confirm successful receipt of the webhook. Failure to do so may result in retries.
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 |
|---|
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. |
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. |
Single Disbursement Events
Due to the nature of single disbursement transactions, there is no webhook event associated to this. Every finalised transaction, the merchant system needs to wait for the response whether the funds have been transferred or not to the intended beneficiary. OneKhusa timeout set for single disbursement transaction is 45 seconds. 
