Important Terminologies

This guide explains the transaction statuses used in Ayoconnect's Instant Transfer (v2) solution and how merchants should handle each status.


Disbursement Status

Disbursement transactions are processed asynchronously. This means the initial Disbursement API response does not necessarily indicate that the transfer has been completed.

Merchants must use the latestTransactionStatus field returned through the Disbursement Callback or Status Inquiry API to determine the transaction outcome.

The following statuses may be returned:

StatusDescriptionRequired Merchant Behavior
00 - SUCCESSThe funds have been successfully transferred to the beneficiary.Mark as Success. Do not retry.
03 - PENDINGThe transfer is still being processed and is awaiting a final result.Keep as Processing. Do not retry.
04 - REFUNDEDA previously successful transfer has been reversed or refunded.Mark as Refunded. Verify the refund before taking further action.
06 - FAILEDThe transfer has failed and the funds were not successfully delivered.Mark as Failed. Review the failure reason before retrying.
07 - NOT FOUNDThe referenced transaction could not be found.Verify the original transaction with Ayoconnect. Do not retry automatically.

State Diagram

Important: For 07 - NOT FOUND, merchants must verify that the original transaction was not processed before considering another disbursement


Pending & Unknown Transaction Status

If a transaction returns 03 – PENDING, merchants MUST keep the transaction as Processing until a definitive outcome is confirmed.

The same requirement applies when the initial Disbursement API returns an HTTP 5xx, 5XX18XX, or timeout response.

Merchants must:

  1. Keep the transaction as Processing.
  2. Wait for the Disbursement Callback.
  3. If no callback is received within 30 minutes, use the Status Inquiry API to verify the transaction status.
  4. Continue monitoring if the final transaction outcome remains unknown.

Important: The 30-minute waiting period is for status verification, not permission to retry. Merchants MUST NOT initiate another disbursement while the original transaction remains unresolved.


Disbursement Status Handling

The following principles must be followed:

  • Successful API acknowledgment does not mean successful fund transfer. A response code of 2021800 indicates that the request has been accepted for processing.
  • HTTP errors do not determine the final transaction outcome. A 5xx response or timeout does not automatically mean the transfer has failed.
  • Retry only after confirming the original transaction outcome. Merchants may initiate another disbursement after the original transaction is confirmed as Failed, or confirmed not to have been processed and safe to resubmit.
  • NOT FOUND does not automatically mean FAILED. Confirm that the original transfer was not processed before considering another attempt.
  • The latest confirmed latestTransactionStatus is the source of truth. Use the Disbursement Callback or Status Inquiry API to determine the transaction outcome.

For detailed handling requirements, refer to:


Did this page help you?