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:

Service code	Service
16	Account Validation
18	Disbursement
36	Status Inquiry
11	Balance Inquiry

Error Codes

HTTP Code	Service Code	Case Code	Response Message	Response Description
200	any	00	Successful	Successful
202	any	00	Request in Progress	Transaction still on process
400	any	00	Bad Request	General request failed error, including message parsing failed.
400	any	01	Invalid Field Format {field name}	Invalid format
400	any	02	Invalid Mandatory Field {field name}	Missing or invalid format on mandatory field
401	any	00	Unauthorized. [reason]	General unauthorized error (No Interface Def, API is Invalid, Oauth Failed, Verify Client Secret Fail, Client Forbidden Access API, Unknown Client, Key not Found)
401	any	01	Invalid Token (B2B)	Token found in request is invalid (Access Token Not Exist, Access Token Expiry)
401	any	02	Invalid Customer Token	Token found in request is invalid (Access Token Not Exist, Access Token Expiry)
401	any	03	Token Not Found (B2B)	Token not found in the system. This occurs on any API that requires token as input parameter
401	any	04	Customer Token Not Found	Token not found in the system. This occurs on any API that requires token as input parameter
403	any	00	Transaction Expired	Transaction expired
403	any	01	Feature Not Allowed [Reason]	This merchant is not allowed to call Direct Debit APIs
403	any	02	Exceeds Transaction Amount Limit	Exceeds Transaction Amount Limit
403	any	03	Suspected Fraud	Suspected Fraud
403	any	04	Activity Count Limit Exceeded	Too many request, Exceeds Transaction Frequency Limit
403	any	05	Do Not Honor	Account or User status is abnormal
403	any	06	Feature Not Allowed At This Time. [reason]	Cut off In Progress
403	any	07	Card Blocked	The payment card is blocked
403	any	08	Card Expired	The payment card is expired
403	any	09	Dormant Account	The account is dormant
403	any	10	Need To Set Token Limit	Need to set token limit
403	any	11	OTP Blocked	OTP has been blocked
403	any	12	OTP Lifetime Expired	OTP has been expired
403	any	13	OTP Sent To Cardholer	initiates request OTP to the issuer
403	any	14	Insufficient Funds	Insufficient Funds
403	any	15	Transaction Not Permitted.[reason]	Transaction Not Permitted
403	any	16	Suspend Transaction	Suspend Transaction
403	any	17	Token Limit Exceeded	Purchase amount exceeds the token limit set prior
403	any	18	Inactive Card/Account/Customer	Indicates inactive account
403	any	19	Merchant Blacklisted	Merchant is suspended from calling any APIs
403	any	20	Merchant Limit Exceed	Merchant aggregated purchase amount on that day exceeds the agreed limit
403	any	21	Set Limit Not Allowed	Set limit not allowed on particular token
403	any	22	Token Limit Invalid	The token limit desired by the merchant is not within the agreed range between the merchant and the Issuer
403	any	23	Account Limit Exceed	Account aggregated purchase amount on that day exceeds the agreed limit
404	any	00	Invalid Transaction Status	Invalid transaction status
404	any	01	Transaction Not Found	Transaction not found
404	any	02	Invalid Routing	Invalid Routing
404	any	03	Bank Not Supported By Switch	Bank not supported by switch
404	any	04	Transaction Cancelled	Transaction is cancelled by customer
404	any	05	Merchant Is Not Registered For Card Registration Services	Merchant is not registered for Card Registration services
404	any	06	Need To Request OTP	Need to request OTP
404	any	07	Journey Not Found	The journeyId cannot be found in the system
404	any	08	Invalid Merchant	Merchant does not exist or status abnormal
404	any	09	No Issuer	No issuer
404	any	10	Invalid API Transition	Invalid API transition within a journey
404	any	11	Invalid Card/Account/Customer [info]/Virtual Account	Card information may be invalid, or the card account may be blacklisted, or Virtual Account number maybe invalid.
404	any	12	Invalid Bill/Virtual Account [Reason]	The bill is blocked/ suspended/not found. Virtual account is suspend/not found.
404	any	13	Invalid Amount	The amount doesn't match with what supposed to
404	any	14	Paid Bill	The bill has been paid
404	any	15	Invalid OTP	OTP is incorrect
404	any	16	Partner Not Found	Partner number can't be found
404	any	17	Invalid Terminal	Terminal does not exist in the system
404	any	18	Inconsistent Request	Inconsistent request parameter found for the same partner reference number/transaction id It can be considered as failed in transfer debit, but it should be considered as success in transfer credit. Considered as success: Transfer credit = (i) Intrabank transfer; (ii) Interbank transfer; (iii) RTGS transfer; (iv) SKNBI transfer; Virtual account = (i) Payment VA; (ii) Payment to VA; Transfer debit = (i) Refund payment; (ii) Void; Considered as failed: Transfer credit = (i) Transfer to OTC; Transfer debit = (i) Direct debit payment; (ii) QR CPM payment; (iii) Auth payment; (iv) Capture;
404	any	19	Invalid Bill/Virtual Account	The bill is expired. Virtual account is expired.
405	any	00	Requested Function Is Not Supported	Requested function is not supported
405	any	01	Requested Opearation Is Not Allowed	Requested operation to cancel/refund transaction Is not allowed at this time.
409	any	00	Conflict	Cannot use same X-EXTERNAL-ID in same day
409	any	01	Duplicate partnerReferenceNo	Transaction has previously been processed indicates the same partnerReferenceNo already success
429	any	00	Too Many Requests	Maximum transaction limit exceeded
500	any	00	General Error	General Error
500	Any	01	Internal Server Error	Unknown Internal Server Failure, Please retry the process again
500	Any	02	External Server Error	Backend system failure, etc
504	any	00	Timeout	timeout from the issuer

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