Response Codes
The Direct Debit API uses conventional HTTP response codes to indicate the result of an API request. For the Payment API, the HTTP response reflects the request handling result and may not represent the final payment outcome.
- 2xx: The request was successfully received and accepted for processing. For the Payment API, the transaction may still be in progress and the final result will be delivered via callback.
- 4xx: The request failed due to invalid or incomplete input, such as missing headers, missing required parameters, or invalid values. The request may be retried after the input is corrected.
- 5xx: An internal error occurred on Ayoconnect’s side or the bank’s side. For the Payment API, this should not be treated as a final failed transaction. The transaction should remain in processing / pending state while waiting for the callback.
If no callback is received within 15 minutes after a 5xx response on the Payment API, the client may call the Payment Status API to retrieve the latest transaction status.
Error responses
Error responses are a combination of the HTTP response code, the service code, and the case code.
Error response = HTTP response code + service code + case code
Service Codes
Below is a list with all the service codes:
| Service code | Service |
|---|---|
| 73 | Generate B2B Token API |
| 74 | Generate B2B2C Token API |
| 07 | Account Binding API |
| 08 | Account Binding Status API |
| 09 | Account Unbinding API |
| 54 | Direct Debit Payment API |
| 55 | Direct Debit Payment Status API |
| 58 | Direct Debit Refund API |
| 04 | Verify OTP API |
Callbacks related to each of the above service APIs will carry the same service code (as laid out above), as part of the the response code returned in the callback
Case Codes
Below is a list of all possible HTTP response codes and case codes, along with additional information about them:
| 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:
|
| 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 |
Updated about 2 months ago
Did this page help you?