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:
| Status | Description | Required Merchant Behavior |
|---|---|---|
| 00 - SUCCESS | The funds have been successfully transferred to the beneficiary. | Mark as Success. Do not retry. |
| 03 - PENDING | The transfer is still being processed and is awaiting a final result. | Keep as Processing. Do not retry. |
| 04 - REFUNDED | A previously successful transfer has been reversed or refunded. | Mark as Refunded. Verify the refund before taking further action. |
| 06 - FAILED | The transfer has failed and the funds were not successfully delivered. | Mark as Failed. Review the failure reason before retrying. |
| 07 - NOT FOUND | The 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:
- Keep the transaction as Processing.
- Wait for the Disbursement Callback.
- If no callback is received within 30 minutes, use the Status Inquiry API to verify the transaction status.
- 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
2021800indicates that the request has been accepted for processing. - HTTP errors do not determine the final transaction outcome. A
5xxresponse 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
latestTransactionStatusis the source of truth. Use the Disbursement Callback or Status Inquiry API to determine the transaction outcome.
For detailed handling requirements, refer to:
Updated 1 day ago