API response codes
Last updated: December 18, 2024
When you perform a request to our API, you'll receive an HTTP status code indicating whether the HTTP request was successful or not.
If you receive a successful 2xx
HTTP response, the response body will contain a response_code
field which specifies the status of the request. The response may also contain additional information in the response_summary
and status
fields.
Information
If you receive an unsuccessful 4xx
HTTP response instead, the response body may contain an error_codes
field. The error code specifies the reason for the request failure.
The five-digit response codes are grouped within code ranges, depending on the code type:
Code range | Code type | Description |
---|---|---|
|
| The request was successful. |
|
| The request was declined, though subsequent attempts may be successful. |
|
| The request was declined. Most hard declines require the issuer or cardholder to rectify the outstanding issue(s) before a subsequent attempt can be made. |
|
| The request triggered a risk response. The status of the response ( |
|
| The request was declined by Checkout.com. |
Information
The response code message text may vary across different endpoint responses.
Response code | Response text | Additional information |
---|---|---|
| Approved | |
| Approved - Honor with ID (Debit Cards) | |
| Partial Value Approved | Returned if a partial authorization was requested. |
| Approved - VIP (not used) | |
| Approved (Country Club) | |
| Approved (Local Banks) | |
| Approved (Approved Commercial) | |
| Flagged as a potentially risky transaction. | |
| Deferred capture |
Information
The response code message text may vary across different endpoint responses.
Response code | Response text | Additional information |
---|---|---|
| Refer to card issuer | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
Contact card issuer | ||
| Refer to card issuer - Special conditions | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Invalid merchant or service provider | The payment failed due to a technical issue. If the issue persists please contact us. |
| Card should be captured | |
| Declined - Do not honour | The payment has been declined by your bank. Try a different card or contact your bank for further support. Refer to our recommendation codes documentation for more information. For payouts, this indicates the transaction was declined by the issuer bank. If you encounter systemic issues or a high percentage of declines for a specific recipient card BIN, contact your Account Manager or [email protected] to report this to Checkout.com. |
| Error / Invalid request parameters | |
| Request in progress | |
| Invalid transaction | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Invalid value/amount | The payment failed due to a technical issue. If the issue persists please contact us. |
| Invalid account number (no such number) | The payment failed, please check your card details and try again with the same or another card. |
| Card not initialised | |
| Customer cancellation | |
| Customer dispute | |
| Re-enter transaction | |
Transaction has expired | ||
| Invalid response | |
| No action taken (unable to back out prior transaction) | |
| Suspected malfunction | |
| Unacceptable transaction fee | |
| File update not supported by the receiver | |
| Unable to locate record on file | |
Account number is missing from the inquiry | ||
| Duplicate file update record | |
| File update field edit error | |
| File is temporarily unavailable | |
| File update not successful | |
| Format error | The payment failed due to a technical issue. Either try again with the same card, or use a different card. MADA transactions may throw this error code under specific circumstances. See Format error in MADA transactions for more information. |
| Bank not supported by Switch | |
| Completed partially | |
| Previous scheme transaction ID invalid | |
| Allowable PIN tries exceeded | |
| No credit account | |
| Requested function not supported | |
| No universal value/amount | |
| No investment account | |
| The Issuer does not support fallback transactions of hybrid-card | |
| Bank decline | The payment has been declined by your bank. Please try a different card or contact your bank for further support. Refer to our recommendation codes documentation. |
| Insufficient funds | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| No current (checking) account | |
| No savings account | |
| Expired card | |
| Incorrect PIN | |
PIN validation not possible | ||
| No card record | |
| Transaction not permitted to cardholder | The payment has been declined by your bank. Please try a different card or contact your bank for further support. For payouts, this indicates the payment was declined by the issuing bank, likely due to a restricted recipient card BIN. Request an alternative payment method from the recipient, or ask them to contact their issuer. If you encounter systemic issues or a high percentage of declines for a specific recipient card BIN, contact your Account Manager or [email protected] to report this to Checkout.com. |
Domestic debit transaction not allowed (Regional use only) | ||
| Transaction not permitted to terminal | |
| Suspected fraud | The payment has been declined by your bank. Please try a different card or contact your bank for further support. Refer to our recommendation codes documentation. |
| Card acceptor contact acquirer | |
| Activity amount limit exceeded | Occurs if the defined amount is exceeded for the account or card. Refer to the page on recommendation codes for suggested action. For payouts, this indicates the payment was declined by the issuer bank or card network. The velocity limits for the recipient card may have been exceeded. Retry the payout the following day. |
| Restricted card | The payment has been declined by your bank. Please try a different card or contact your bank for further support. Refer to our recommendation codes documentation. |
| Security violation | |
| Transaction does not fulfil AML requirement | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Exceeds Withdrawal Frequency Limit | The payment has been declined by your bank. Please try a different card or contact your bank for further support. For payouts, this indicates the payment was declined by the issuer bank or card network. The velocity limits for the recipient card may have been exceeded. Retry the payout the following day. |
| Card acceptor call acquirer security | |
| Hard capture - Pick up card at ATM | |
| Response received too late / Timeout | The payment failed due to a technical issue. Please try again with the same card, or use a different card. |
Internal error | ||
| Allowable PIN-entry tries exceeded | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Blocked at first use - transaction from new or replacement card that is not properly unblocked | The payment has been declined by your bank. Please try a different card or contact your bank for further support. Refer to our recommendation codes documentation. |
| Card is local use only | |
| No security model | |
PIN cryptographic error found (error found by VIC security module during PIN decryption) | ||
Negative CAM, dCVV, iCVV, or CVV results | ||
| No accounts | |
| No PBF | |
| PBF update error | |
| ATM malfunction | |
Invalid authorization type | ||
| Bad track data (invalid CVV and/or expiry date) | The payment failed, please check your card details and try again with the same or another card. |
| Unable to dispense/process | |
| Administration error | |
| Cut-off in progress | |
| Issuer unavailable or switch is inoperative | The payment failed due to a technical issue. Try again with the same card, or use a different card. For payouts, this indicates that the issuer host system may be down, or connectivity was lost. Retry the payout when the connection issues have been resolved. |
| Destination cannot be found for routing | |
| Transaction cannot be completed; violation of law | The payment has been declined by your bank. Please try a different card or contact your bank for further support. Refer to our recommendation codes documentation. |
| Duplicate transmission / invoice | |
| Reconcile error | |
| System malfunction | The payment failed due to a technical issue. Please try again with the same card, or use a different card. |
| Reconciliation totals reset | |
| MAC error | |
| Other / Unidentified responses | The payment failed due to a technical issue. If the issue persists please contact us. |
| The ATM/POS terminal number has not been registered | |
| Cardholder ID verification failed | Cardholder could not be identified from their ID documentation as part of Know Your Customer (KYC) checks. The cardholder should contact their issuing bank to resolve. |
| Transaction with defect, contact issuer | The requests have not been received. |
| The original transactions are rejected. | |
| UnionPay forwarded the original request, but did not receive a response from the issuer. | |
| Unauthorised access | |
| Signature verification failure | |
| System busy, please try again later | |
| Force STIP | |
| Decline for CVV2 failure | |
| PIN required | |
| Over daily limit | |
| Limit exceeded. Enter a lesser value. | |
| Issuer initiated a stop payment (revocation order) for this authorization | The cardholder has canceled this subscription |
| Issuer initiated a stop payment (revocation order) for all authorizations | The cardholder has canceled all subscriptions |
| PTLF full | |
| Invalid transaction date | |
| Card not supported | |
| CAF status = 0 or 9 | |
| Invalid expiry date format | The payment failed due to invalid expiry date. Please try again providing the correct value. |
| No Account / No Customer (Token is incorrect or invalid) | |
| Invalid merchant / wallet ID | The payment failed due to a technical issue. If the issue persists please contact us. |
| Card type / payment method not supported | The payment has been declined by your bank. Please try again with a different card or contact your bank for further support. |
| Gateway reject - Invalid transaction | The payment failed due to a technical issue. Please try again with the same card, or use a different card. |
| Gateway reject - Violation | The payment failed due to a technical issue. Please try again with the same card, or use a different card. |
| Unsupported currency | |
| Billing address is missing | |
| Declined - Updated cardholder available | |
| Transaction already reversed (voided) | |
Previous message located for a repeat or reversal, but repeat or reversal data is inconsistent with the original message | ||
Capture is larger than initial authorized value | ||
| Authorization completed | |
| Transaction already reversed | The payment reversal has already been processed. |
| Merchant not Mastercard SecureCode enabled | The payment failed due to a technical issue. Please contact us with the payment reference number. |
| Invalid property | |
| Token is incorrect | |
| Missing / Invalid lifetime | |
| Invalid encoding | |
| Invalid API version | The payment failed due to a technical issue. If the issue persists please contact us. |
| Transaction pending | The payment failed due to a technical issue. If the issue persists please contact us. |
| Invalid batch data and/or batch data is missing | The payment failed due to a technical issue. If the issue persists please contact us. |
| Invalid customer/user | The payment failed due to a technical issue. If the issue persists please contact us. |
| Transaction limit for merchant/terminal exceeded | |
| Mastercard installments not supported | |
| Missing basic data: zip, addr, member | The payment failed due to a technical issue. If the issue persists please contact us. |
| Missing CVV value, required for ecommerce transaction | |
| Card not 3D Secure (3DS) enabled | |
| Cardholder failed 3DS authentication | |
| Initial 3DS transaction not completed within 15 minutes | The payment has expired due to inactivity. Please try again with the same card, or use a different card. |
| 3DS system malfunction | The payment failed due to a technical issue. Please try again with the same card, or use a different card. |
| 3DS authentication required | The payment declined due to Strong Customer Authentication (3DS). Please try again with the same card, or use a different card. |
| 3DS authentication service provided invalid authentication result | |
| Requested function not supported by the acquirer | |
| Invalid merchant configurations - Contact Support | |
| Refund validity period has expired | |
| ACS Malfunction | The payment failed due to a technical issue with the ACS used to perform 3DS authentication. If the issue persists, contact Checkout.com. |
| Lifecycle | Occurs when transaction has invalid card data. Refer to the page on recommendation codes for suggested action. |
| Policy | Occurs when a transaction does not comply with card policy. Refer to the page on recommendation codes for suggested action. |
| Security | Occurs when a transaction is suspected to be fraudulent. Refer to the page on recommendation codes for suggested action. |
| Invalid country code |
Information
The response code message text may vary across different endpoint responses.
Response code | Response text | Additional information |
---|---|---|
| Pick up card (No fraud) | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Pick up card - Special conditions | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| No such issuer | The payment has been declined due to incorrect details. Please try again with updated details. For payouts, this indicates that the recipient card number is incorrect, invalid, or restricted. Request an alternative payment method from the recipient, or ask them to contact their issuer. If you encounter systemic issues or a high percentage of declines for a specific recipient card BIN, report this to Checkout.com. |
| Issuer does not allow online gambling payout | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Issuer does not allow original credit transaction | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Issuer does not allow money transfer payout | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Issuer does not allow non-money transfer payout | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Invalid amount | The payment failed due to a technical issue. If the issue persists please contact us. |
| Total amount limit reached | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Total transaction count limit reached | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Expired card - Pick up | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Suspected fraud - Pick up | The payment has been declined by your bank. Please contact your bank for further support. For payouts, this indicates the payment was declined by the issuer bank, likely due to suspected fraud. Ask the cardholder to contact their issuer and do not reattempt a payout. |
| Contact acquirer - Pick up | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Restricted card - Pick up | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Call acquirer security - Pick up | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Allowable PIN tries exceeded - Pick up | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Lost card - Pick up | The payment has been declined by your bank. Please try a different card or contact your bank for further support. |
| Stolen card - Pick up | The cardholder’s bank has declined the payment because the card has been reported stolen.
|
| Transaction rejected - AMLD5 | Transaction was initiated from an anonymous, non-reloadable prepaid card and for an amount greater than 50 EUR. Due to the AMLD5 directive, it cannot be fulfilled. |
| Invalid payout fund transfer type | If the fund transfer type is not among the list that was configured for allowed funds transfer types, the transaction would fail. |
| Closed account | The payment has been declined by your bank. Please contact your bank for further support. |
Risk responses are triggered by our risk engine.
Information
The response code message text may vary across different endpoint responses.
Response code | Response text | Additional information |
---|---|---|
| Risk blocked transaction | The payment failed due to a security violation. See the Transaction declined with error code 40101 support article to troubleshoot this response code. To receive new response codes with detailed summaries, contact your Account Manager or [email protected]. |
| Gateway reject - card number blocklist | To receive new response codes with detailed summaries, contact your Account Manager or [email protected]. |
| Gateway reject - IP address blocklist | To receive new response codes with detailed summaries, contact your Account Manager or [email protected]. |
| Gateway reject - email blocklist | To receive new response codes with detailed summaries, contact your Account Manager or [email protected]. |
| Gateway reject - phone number blocklist | To receive new response codes with detailed summaries, contact your Account Manager or [email protected]. |
| Gateway Reject - BIN number blocklist | To receive new response codes with detailed summaries, contact your Account Manager or [email protected]. |
Response code | Response text | Additional information |
---|---|---|
| Risk decline - {Name of the rule} | The transaction was declined due to a client-level rule configured in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Card number | The transaction was declined because the associated card number is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - BIN | The transaction was declined because the associated BIN is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Email address | The transaction was declined because the associated email address is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Phone | The transaction was declined because the associated phone number is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Payment IP | The transaction was declined because the associated payment IP is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Email domain | The transaction was declined because the associated email domain is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Fraud score exceeds threshold | The transaction was declined because it was flagged as high risk by our fraud model score. If you've not opted in to receive the new response codes, you receive a |
Response code | Response text | Additional information |
---|---|---|
| Risk decline - {Name of the rule} | The transaction was declined due to an entity-level rule configured in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Card number | The transaction was declined because the associated card number is on an entity-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - BIN | The transaction was declined because the associated BIN is on an entity-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Email address | The transaction was declined because the associated email address is on an entity-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Phone | The transaction was declined because the associated phone number is on an entity-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Payment IP | The transaction was declined because the associated payment IP is on an entity-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Email domain | The transaction was declined because the associated email domain is on a client-level decline list in your account. If you've not opted in to receive the new response codes, you receive a |
| Fraud score exceeds threshold | The transaction was declined because it was flagged as high risk by our fraud model score. If you've not opted in to receive the new response codes, you receive a |
Response code | Response text | Additional information |
---|---|---|
| Potential fraud risk | The transaction was declined because it was flagged as high risk by our fraud model. If you've not opted in to receive the new response codes, you receive a |
| Risk decline - {Name of the rule} | The transaction was declined because of a Checkout.com decline rule. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Card number | The transaction was declined because the associated card number is on Checkout.com's decline list. If you've not opted in to receive the new response codes, you receive a |
| Decline list - BIN | The transaction was declined because the associated BIN is on Checkout.com's decline list. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Email address | The transaction was declined because the associated email address on Checkout.com's decline list. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Phone | The transaction was declined because the associated phone number is on Checkout.com's decline list. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Payment IP | The transaction was declined because the associated payment IP is on Checkout.com's decline list. If you've not opted in to receive the new response codes, you receive a |
| Decline list - Email domain | The transaction was declined because the associated email domain is on Checkout.com's decline list. If you've not opted in to receive the new response codes, you receive a |
| Fraud score exceeds threshold | The transaction was declined because it was flagged as high risk by our fraud model score. If you've not opted in to receive the new response codes, you receive a |
| 3DS authentication required | The transaction was declined because additional authentication is required for processing. Reattempt the transaction with 3D Secure. If you've not opted in to receive the new response codes, you receive a |
Information
The response code message text may vary across different endpoint responses.
Response code | Response text | Additional information |
---|---|---|
| Compliance error | |
| Sanction screening failure | Sanctions screening hit or data corruption. |
| Balance reservation insufficient funds | Insufficient available balance in sub-account. |
| Barred Beneficiary Error | |
| Recipient error | |
| Invalid recipient error | |
| Unsupported recipient error | |
| Recipient limit error | |
| Invalid Recipient Account Error | |
| Recipient Account Not Found | |
| Recipient Bank Error | |
| Invalid Recipient Details Error | |
| Sender error | |
| Instruction error | |
| Instruction amount limit error | |
| Instruction amount limit sender error | |
| Instruction amount limit recipient error | |
| Velocity limit | |
| Velocity limit sender error | |
| Velocity limit recipient limit error | |
| Processing error | |
| Validation error | |
| Configuration error | |
| Cancellation error | |
| Returned error | |
| Insufficient funds | |
| Unmapped response | |
| Bank details invalid | |
| Account not found | |
| Account inactive | |
| Account dormant | |
| Account number invalid | |
| Branch not found | |
| Branch code invalid | |
| Branch code required | |
| Bank code invalid | |
| Bank code required | |
| Account type required | |
| Account holder details invalid | |
| Account holder identification number required | |
| Account holder type not supported | |
| Account holder type not allowed | |
| Account closed | |
| Account blocked | |
| Invalid debtor account type | |
| Duplicate Payment | |
| Account holder billing address details incorrect | |
| Account holder billing address details required | |
| Account holder billing address can not be PO box | |
| Payout Returned | |
| Unsupported characters | |
| Invalid amount | |
| Minimum amount not met | |
| Exceeded transaction value | |
| Exceeded daily limit | |
| Exceeded weekly limit | |
| Exceeded monthly limit | |
| Recalled | |
| Unknown reason |
A Declined - Do not honour
notification is a request status associated with the 20005
response code.
This status indicates that the customer's bank has declined the payment and is the most common message that banks provide when a payment fails their authorization process.
This decline response means that the issuing bank has provided no further details about the payment failure, and Checkout.com cannot override the response.
The payment may have been declined due to failed CVV or Address Verification Service (AVS) checks. We recommend verifying that these fields are correct in your payment request before you attempt alternative solutions.
There are several possible scenarios that can trigger the 20005 (Declined - Do not honour)
response code:
- the bank's fraud rules (which consider various factors that are not made public) have been triggered
- the bank may have placed a temporary hold on the customer's card
- the purchase session may have been locked due to multiple declined payments
- the seller is located in a country different from that of the card issuing bank
To resolve a 20005 (Declined - Do not honour)
response, you should contact the customer and request that they:
- contact their bank, explaining that they are trying to process a payment — the customer can then ask the bank to allow the payment
- try again at a later time — the issuing bank may have only placed a temporary hold on the card
- use an alternative payment card
Checkout.com response codes are standardized across schemes and payment methods to enable easier integration and analysis of transactions.
For card payments, we also provide the original authorization response code sent by the scheme in the response's partner_response_code
field. This is also referred to as the raw response code.
The partner_response_code
field is returned in:
Information
To enable the partner_response_code
feature, contact your Account Manager or [email protected].
The values differ from scheme to scheme and are subject to change. Refer to the scheme specific documentation for further details.
1{2"response_code": "20051",3"response_summary": "Insufficient funds",4"processing": {5"scheme": "visa",6"partner_response_code": "51"7}8}
1{2"id": "pay_tb4f46qcj6runb3pmbsrrdqd74",3"action_id": "act_ixmhjuu4brpu7lw4dkny4bfcam",4"amount": 0,5"auth_code": "656280",6"currency": "EUR",7"payment_type": "Regular",8"processed_on": "2023-12-15T16:50:16.9557112Z",9"processing": {10"acquirer_transaction_id": "371551175125650580188",11"retrieval_reference_number": "583063115397",12"scheme": "MASTERCARD",13"partner_response_code": "51"14},15"response_code": "20051",16"response_summary": "Insufficient Funds",17"risk": {18"flagged": false19},20"scheme_id": "885825379894893",21"source": {22"id": "src_u3p3boigodfu3hcqo6ini2ofwe",23"type": "card",24"billing_address": {},25"expiry_month": 10,26"expiry_year": 2028,27"scheme": "MASTERCARD",28"last_4": "9682",29"fingerprint": "3C2C9685923907BAC9BB646F83E3799E40FC628147F25F76745A0B9296D769AC",30"bin": "543782",31"card_type": "CREDIT",32"card_category": "CONSUMER",33"issuer": "TAISHIN INTERNATIONAL BANK",34"issuer_country": "TW",35"product_id": "MCS",36"product_type": "Standard MasterCard(r) Card",37"avs_check": "S",38"cvv_check": "Y"39},40"event_links": {41"payment": "https://api.sandbox.checkout.com/payments/pay_tb4f46qcj6runb3pmbsrrdqd74",42"payment_actions": "https://api.sandbox.checkout.com/payments/pay_tb4f46qcj6runb3pmbsrrdqd74/actions"43},44"action_invocations": [45{46"workflow_id": "wf_wdodk5vudmrubb5us6zefyaepe",47"workflow_action_id": "wfa_zb7vtvprtipu5l3trvk2m7je6y",48"status": "successful",49"_links": {50"self": {51"href": "https://api.sandbox.checkout.com/workflows/events/evt_igyyma6msoledm57qy4efdihhy/actions/wfa_zb7vtvprtipu5l3trvk2m7je6y"52}53}54}55],56"_links": {57"self": {58"href": "https://api.sandbox.checkout.com/workflows/events/evt_igyyma6msoledm57qy4efdihhy"59},60"payment_actions": {61"href": "https://api.sandbox.checkout.com/payments/pay_tb4f46qcj6runb3pmbsrrdqd74/actions"62},63"payment": {64"href": "https://api.sandbox.checkout.com/payments/pay_tb4f46qcj6runb3pmbsrrdqd74"65}66}67}
The table below describes the possible HTTP response codes you can receive when sending an API request.
Code | Description |
---|---|
| OK |
| Created |
| Accepted |
| Unauthorized |
| Not allowed |
| Not found |
| Conflict with another request being processed |
| Invalid data was sent |
| Too many requests |
| Internal server error |
| Bad gateway |