Errors

The Card Acceptance API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

codes in the 2xx range indicate success
codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a header is missing, etc.
codes in the 5xx range indicate an error with Ayoconnect system
codes with exactly 503 indicate an error with Supplier system

As our API can raise errors for many reasons, such as a failed charge, invalid parameters, authentication errors.. we recommend writing code that gracefully handles all possible error codes.

All the errors include an error code and a short human-readable message that briefly explains the error reported (you can use it internally but don't share it with your clients/users).

Error responses

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

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

Service Codes

Below is a list with all the service codes:

Service code	Service
01	Card Registration
03	Get Card
04	Unbinding
54	Payment Charge
55	Get Payment Status
57	Payment Void
58	Payment Refund

HTTP Response Codes

Below is a list of possible HTTP response codes, along with additional information about them:

HTTP Response	Message	Description
400	Bad Request	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401	Unauthorized	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403	Forbidden	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
404	Not Found	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client.
409	Conflict	This response is sent when a request conflicts with the current state of the server.
429	Too Many Requests	The user has sent too many requests in a given amount of time.
500	Internal Server Error	The server has encountered a situation it does not know how to handle.
503	Service Unavailable	External third party or supplier failure
504	Gateway Timeout	This error response is given when the server is acting as a gateway and cannot get a response in time.

Case Codes

Below is a list of all Internal possible HTTP response codes and case codes, along with additional information about them:

HTTP Code	Service Code	Case Code	Response Message	Response Description
400	XX	00	Bad Request	General Request Failed Error
400	XX	01	Invalid Field Format '{fieldName}'	'{fieldName}' is invalid
400	XX	02	Invalid Mandatory Field	A required field is missing or invalid
400	XX	03	Duplicate Field Value	The field value is duplicated
401	XX	00	Unauthorized	Unauthorized Error
401	XX	01	Invalid token (B2B)	B2B Token is invalid
401	XX	02	Invalid Customer Token	The Customer Token is invalid
401	XX	03	Token Not found (B2B)	The B2B Token Not Found
401	XX	04	Customer Token Not Found	The customer token not found
403	XX	00	Transaction Expired	The transaction has expired
403	XX	01	Featured not allowed	The requested feature not allowed
403	XX	02	Exceeds Transaction Amount Limit	The transaction amount exceeds the allowed limit
403	XX	03	Suspected Fraud	The transaction is suspected to be fraudulent
403	XX	04	Activity Count Limit Exceeded	The number of requests exceeded the limit
403	XX	05	Do Not Honor	The transaction was not honored by supplier
403	XX	06	Do Not Honor	The transaction was not honored by supplier
403	XX	07	Do Not Honor	The transaction was not honored by supplier
403	XX	08	Do Not Honor	The transaction was not honored by supplier
403	XX	09	Dormant Account	The account is dormant and cannot process transaction
403	XX	12	OTP lifetime expired	The OTP has expired
403	XX	14	Insufficient Funds	There are insufficient funds in the account
403	XX	15	Transaction Not Permitted	The transaction is not permitted
403	XX	16	Suspend Transactions	The transaction has been suspended
403	XX	18	Inactive Card/Account/Customer	The account or customer is inactive
403	XX	19	Merchant Blacklisted	The merchant is blacklisted
403	XX	20	Merchant Limit Exceeded	The merchant has exceeded their transaction limit
403	XX	23	Account Limit Exceeded	The account has exceeded its limit
403	XX	24	Customer Not Found	The customer could not be found
403	XX	25	Merchant Not Found	The merchant could not be found
403	XX	26	No Data Found	No data was found matching the request
404	XX	00	Invalid Transaction Status	The transaction status is invalid
404	XX	01	Transaction Not Found	The specified transaction could not be found
404	XX	04	Transaction Cancelled	The transaction was cancelled by customer
404	XX	08	Invalid Merchant	The merchant id is invalid
404	XX	13	Invalid Amount	The specified amount is invalid
404	XX	15	Invalid OTP	The OTP provided is Invalid
404	XX	16	Registration/Account Token Not Found	The registration or account token could not be found
409	XX	00	Too Many Requests	The maximum transaction limit has been exceeded
409	XX	01	Duplicate partnerReferenceNo	A duplicate partner reference number was found
409	XX	02	Customer exist for this phone number	A customer already exists with the specified phone number
409	XX	03	Duplicate Entry	The entry is a duplicate
500	XX	00	General Error	Unknown internal server failure
500	XX	01	Internal Server Error	An internal server error occurred
504	XX	00	Timeout	The request timed out

In Card Acceptance, all error that starts with 503 will be considered as external error from suppliers.

Below is a list of all External possible HTTP response codes and case codes:

HTTP Code	Service Code	Case Code	Response Description
503	XX	00	ABORTED
503	XX	01	ACQUIRER_SYSTEM_ERROR
503	XX	02	AUTHENTICATION_FAILED
503	XX	03	AUTHENTICATION_IN_PROGRESS
503	XX	04	BLOCKED
503	XX	05	CANCELLED
503	XX	06	DECLINED
503	XX	07	DECLINED_AVS
503	XX	08	DECLINED_AVS_CSC
503	XX	09	DECLINED_CSC
503	XX	10	DECLINED_DO_NOT_CONTACT
503	XX	11	DECLINED_INVALID_PIN
503	XX	12	DECLINED_PAYMENT_PLAN
503	XX	13	DECLINED_PIN_REQUIRED
503	XX	14	DEFERRED_TRANSACTION_RECEIVED
503	XX	15	DUPLICATE_BATCH
503	XX	16	EXCEEDED_RETRY_LIMIT
503	XX	17	EXPIRED_CARD
503	XX	18	INSUFFICIENT_FUNDS
503	XX	19	INVALID_CSC
503	XX	20	LOCK_FAILURE
503	XX	21	NOT_ENROLLED_3D_SECURE
503	XX	22	NOT_SUPPORTED
503	XX	23	NO_BALANCE
503	XX	24	PARTIALLY_APPROVED
503	XX	25	PENDING
503	XX	26	REFERRED
503	XX	27	SUBMITTED
503	XX	28	SYSTEM_ERROR
503	XX	29	TIMED_OUT
503	XX	30	UNKNOWN
503	XX	31	UNSPECIFIED_FAILURE
503	XX	32	EXTERNAL_VERIFICATION_BLOCKED
503	XX	33	EXTERNAL_VERIFICATION_DECLINED
503	XX	34	EXTERNAL_VERIFICATION_DECLINED_AUTHENTICATION_REQUIRED
503	XX	35	EXTERNAL_VERIFICATION_DECLINED_EXPIRED_CARD
503	XX	36	EXTERNAL_VERIFICATION_DECLINED_INVALID_CSC
503	XX	37	EXTERNAL_VERIFICATION_PROCESSING_ERROR
503	XX	38	NO_VERIFICATION_PERFORMED
503	XX	39	SCHEME_TOKENIZATION_DECLINED
503	XX	40	SCHEME_TOKENIZATION_ERROR
503	XX	41	SCHEME_TOKENIZATION_SUCCESSFUL_ADDITIONAL_AUTHENTICATION_REQUIRED