API Flows

Flows

There are 2 main flows and 2 supporting flowsthat you can perform using Ayoconnect's Instant Transfer Solution:

Type	Flow	Details	Execution Mode
Main	Account Validation	Checks and confirms that the beneficiary’s bank account is valid and can receive funds before any transfer is made.	Asynchronous
Main	Trigger Transfer	Starts the fund transfer (disbursement) to the verified beneficiary. After the request is triggered, the final transfer result is sent asynchronously via callback.	Asynchronous
Supporting	Status Inquiry	Checks the latest status of a transfer when the callback is delayed or when the status needs to be reconfirmed.	Synchronous
Supporting	Balance Inquiry	Retrieves the merchant’s current available balance, including top-ups and deductions from completed transfers or disbursements.	Synchronous

Account Validation

Trigger Transfer

Status Inquiry

Balance Inquiry

X-EXTERNAL-ID Requirement

A unique X-EXTERNAL-ID header must be provided when initiating any Instant Transfer API flow. This value is used by Ayoconnect as the primary identifier for transaction tracking and validation.

Reusing an existing X-EXTERNAL-ID value will result in a conflict error and the request will not be processed.

Guidelines

Please follow the guidelines below carefully for all the flows:

1. Account Validation must be performed before every disbursement.

Every disbursement to a beneficiary requires a successful Account Validation API call before calling the Trigger Transfer (Disbursement) API. Account validation is mandatory for every transaction, even if the same beneficiary has been validated in a previous transfer.

2. Instant Transfer APIs consist of both asynchronous and synchronous flows.

Account Validation and Trigger Transfer are asynchronous APIs. The initial response typically returns a Processing status, and the final result is delivered through callbacks.
Status Inquiry and Bank Balance Inquiry are synchronous APIs, where the result is returned directly in the API response

3. Transfer Status Inquiry is optional in the normal flow.

In the standard flow (Account Validation → Trigger Transfer), Status Inquiry is not required, as the final transaction status is automatically delivered via callback. This API should only be used when necessary, for example when a disbursement remains in Pending status longer than expected and an active status check is required.

4. Pending transactions must not be marked as Failed before the final callback is received.

A transaction must remain in Pending status until the final status callback is received from Ayoconnect. HTTP 5xx errors returned by the disbursement API do not indicate that the transfer has failed. These errors are typically caused by server timeouts while the transaction is still being processed. In such cases, the transaction must remain Pending until the callback is received.

5. Idempotency is enforced exclusively using the X-EXTERNAL-ID header.

Each disbursement transaction is identified using the X-EXTERNAL-ID header, which must be unique for every disbursement request. If a request is sent with an X-EXTERNAL-ID that has already been used, the system will return a conflict error and the request will not be processed again.

X-EXTERNAL-ID is not an idempotency key. Resending the same request with the same X-EXTERNAL-ID will trigger a conflict error. To check the status of a disbursement, the same X-EXTERNAL-ID used in the Trigger Transfer (disbursement) request must be provided when calling the Status Inquiry API.

6. Transaction status handling on Disbursement

Successful 2xx response from the Trigger Transfer (Disbursement) API only means that the transfer request has been received and processed by the system, it does not mean that the transfer has been completed. After receiving a successful Trigger Transfer response, the transaction must be put in Pending state.

If the callback has not been received yet, the transaction must stay in Pending state. The transaction status must be updated only after receiving the final latestTransactionStatus value from either the callback or the Transfer Status Inquiry API, not from the initial Trigger Transfer (Disbursement) response.

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

If the value is 03, the transaction must remain Pending / Processing.
If the value is 00, update the status to Success.
If the value is 04, update the status to Refunded.
If the value is 06, update the status to Failed.
If the value is 07, update the status to Not Found.

7. Fallback handling for unknown or abnormal status

If a transaction returns an unexpected status, an abnormal condition, or a status that is not listed in the supported flow for the merchant, the transaction must be treated as Pending.

The transaction must remain Pending until a valid and recognized latestTransactionStatus is received via callback or Status Inquiry.