Response Codes

Ayoconnect's Instant Transfer APIs use conventional HTTP response codes to indicate the result of an API request. However, for asynchronous APIs, the HTTP response reflects the request handling result and may not represent the final transaction outcome.

In general:

• 2xx indicates that the request was successfully received and accepted for processing. For Account Validation and Disbursement, this does not mean the final result is already available, as the transaction should still be in progress and the final status will be delivered via callback. For Status Inquiry and Balance Inquiry, the result is returned directly in the API response.
• 4xx indicates that the request failed due to invalid or incomplete input, such as a missing header, missing required parameter, or invalid value. The request may be retried after the request is corrected.
• 5xx indicates an internal error on Ayoconnect’s side or the bank’s side. For Account Validation and Disbursement, this should not be treated as a final failed request. The request should remain in Pending / Processing state while waiting for the callback.
• 5xx indicates an internal error on Ayoconnect’s side or the bank’s side. For asynchronous APIs (such as Account Validation and Disbursement), this should not be treated as the final request result. The transaction / request should remain in Pending / Processing state while waiting for the callback.

If no callback is received within 15 minutes after a 5xx response on the Disbursement API, the client may call the Status Inquiry API using the same X-EXTERNAL-ID to retrieve the latest transaction status.

For Disbursement, if a 5xx response is received, the transaction must remain in Pending / Processing state while waiting for the callback. If no callback is received within 15 minutes, the client may call the Status Inquiry API using the same X-EXTERNAL-ID to retrieve the latest transaction status.

For Account Validation, the callback is typically received within a few seconds. If no callback is received within 15 seconds, the same request may be resent using the same request identifier (same idempotency key) to check whether the original request is already being processed. If no callback is received within 1 minute, the request may be retried.

As the API may return errors for different reasons, such as invalid parameters, authentication issues, or downstream processing issues, the integration should handle all possible HTTP response codes gracefully.

All error responses include an error code and a short human-readable message describing the reported issue.

Error responses

Error responses are represented by a combination of the HTTP response code, service code, and case code.

Error response = HTTP response code + service code + case code

Service Codes

Below is a list with all the Instant Transfer service codes:

Error Codes

Notes:

• These error codes are only reasons of failure, not determining the transaction status
• Always determine transaction status from the 'status' field from the Callback, not Response