Guides

Disbursement API

Service Code: 18

Disbursement API is used to initiate a fund transfer to a validated beneficiary account.

Before calling the Disbursement API, a successful Account Validation is required. The customerReference value returned from the successful Account Validation callback, under additionalInfo.customerReference, must be included in the Disbursement request.

A response code 2021800 indicates that the disbursement request has been successfully received and is currently being processed. It does not mean that the transfer has been completed.

The final transaction result must be determined from the callback or, when needed, by calling the Status Inquiry API.

Merchants must rely on the latestTransactionStatus field to determine the transaction result:

  • 00 - Success: the disbursement has been completed successfully
  • 03 - Pending: the disbursement is still being processed
  • 04 - Refunded: the disbursement has been refunded
  • 06 - Failed: the disbursement failed
  • 07 - Not Found: the transaction could not be found

If a 5XX18XX response code is received, the transaction must not be marked as failed immediately. This response indicates a temporary system issue, and the final transaction status may not yet be available at the time of the response. In this case, wait for the callback for up to 15 minutes. If no callback is received within that period, call the Status Inquiry API using the same externalId value into originalExternalId to retrieve the latest transaction status.

The final transaction outcome must always be based on the latestTransactionStatus value returned in the callback or Status Inquiry response. Do not determine the transaction result based solely on the HTTP response code or the initial Disbursement response.

Important Notes:

  • A successful Disbursement response only means the request has been accepted for processing.
  • A response code 2021800 indicates that the transaction is still being processed.
  • Do not mark the transaction as failed only because a 5xx HTTP response or 5XX18XX response code is received.
  • If the callback is delayed, the transaction status may be checked using the Status Inquiry API.
  • Always use the latest latestTransactionStatus value as the source of truth for transaction status handling.
  • The customerReference from the successful Account Validation callback is mandatory for the Disbursement request.

Transaction Status Handling

The transaction status must be handled based on the latestTransactionStatus value as follows:

  • 00 → mark as Success
  • 03 → keep as Pending / Processing
  • 04 → mark as Refunded
  • 06 → mark as Failed
  • 07 → mark as Failed / Not Found, based on merchant-side handling

Disbursement Flow Sequence

The following sequence must be followed when performing a disbursement:

  1. Call Account Validation API
    Submit the beneficiary account details for validation.
  2. Wait for Account Validation callback
    Retrieve the customerReference value from additionalInfo.customerReference in the callback.
  3. Call Disbursement API
    Submit the disbursement request using the validated customerReference.
  4. Wait for Disbursement callback Use the callback to determine the latest transaction status.
  5. Call Status Inquiry API if needed If no callback is received within 30 minutes, call the Status Inquiry API using the same X-EXTERNAL-ID