API response codes

Last updated: November 28, 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
`10xxx`	`APPROVED`	The request was successful.
`20xxx`	`SOFT DECLINE`	The request was declined, though subsequent attempts may be successful.
`30xxx`	`HARD DECLINE`	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.
`40xxx`	`RISK RESPONSES`	The request triggered a risk response. The status of the response (`response_code` and `status`) will depend on the action specified in your risk settings.
`50xxx`	`CHECKOUT.COM DECLINE`	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
`10000`	Approved
`10008`	Approved - Honor with ID (Debit Cards)
`10010`	Partial Value Approved	Returned if a partial authorization was requested.
`10011`	Approved - VIP (not used)
`10076`	Approved (Country Club)
`10077`	Approved (Local Banks)
`10081`	Approved (Approved Commercial)
`10100`	Flagged as a potentially risky transaction.
`10200`	Deferred capture

Information

The response code message text may vary across different endpoint responses.

Response code	Response text	Additional information
`20001`	Refer to card issuer	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`20001`	Contact card issuer
`20002`	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.
`20003`	Invalid merchant or service provider	The payment failed due to a technical issue. If the issue persists please contact us.
`20004`	Card should be captured
`20005`	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.
`20006`	Error / Invalid request parameters
`20009`	Request in progress
`20012`	Invalid transaction	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`20013`	Invalid value/amount	The payment failed due to a technical issue. If the issue persists please contact us.
`20014`	Invalid account number (no such number)	The payment failed, please check your card details and try again with the same or another card.
`20016`	Card not initialised
`20017`	Customer cancellation
`20018`	Customer dispute
`20019`	Re-enter transaction
`20019`	Transaction has expired
`20020`	Invalid response
`20021`	No action taken (unable to back out prior transaction)
`20022`	Suspected malfunction
`20023`	Unacceptable transaction fee
`20024`	File update not supported by the receiver
`20025`	Unable to locate record on file
`20025`	Account number is missing from the inquiry
`20026`	Duplicate file update record
`20027`	File update field edit error
`20028`	File is temporarily unavailable
`20029`	File update not successful
`20030`	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.
`20031`	Bank not supported by Switch
`20032`	Completed partially
`20033`	Previous scheme transaction ID invalid
`20038`	Allowable PIN tries exceeded
`20039`	No credit account
`20040`	Requested function not supported
`20042`	No universal value/amount
`20044`	No investment account
`20045`	The Issuer does not support fallback transactions of hybrid-card
`20046`	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.
`20051`	Insufficient funds	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`20052`	No current (checking) account
`20053`	No savings account
`20054`	Expired card
`20055`	Incorrect PIN
`20055`	PIN validation not possible
`20056`	No card record
`20057`	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.
`20057`	Domestic debit transaction not allowed (Regional use only)
`20058`	Transaction not permitted to terminal
`20059`	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.
`20060`	Card acceptor contact acquirer
`20061`	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.
`20062`	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.
`20063`	Security violation
`20064`	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.
`20065`	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.
`20066`	Card acceptor call acquirer security
`20067`	Hard capture - Pick up card at ATM
`20068`	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.
`20068`	Internal error
`20075`	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.
`20078`	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.
`20081`	Card is local use only
`20082`	No security model
	PIN cryptographic error found (error found by VIC security module during PIN decryption)
	Negative CAM, dCVV, iCVV, or CVV results
`20083`	No accounts
`20084`	No PBF
`20085`	PBF update error
`20086`	ATM malfunction
`20086`	Invalid authorization type
`20087`	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.
`20088`	Unable to dispense/process
`20089`	Administration error
`20090`	Cut-off in progress
`20091`	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.
`20092`	Destination cannot be found for routing
`20093`	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.
`20094`	Duplicate transmission / invoice
`20095`	Reconcile error
`20096`	System malfunction	The payment failed due to a technical issue. Please try again with the same card, or use a different card.
`20097`	Reconciliation totals reset
`20098`	MAC error
`20099`	Other / Unidentified responses	The payment failed due to a technical issue. If the issue persists please contact us.
`20197`	The ATM/POS terminal number has not been registered
`2006P`	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.
`200A4`	Transaction with defect, contact issuer	The requests have not been received.
`200A5`		The original transactions are rejected.
`200A6`		UnionPay forwarded the original request, but did not receive a response from the issuer.
`200E0`	Unauthorised access
`200E2`	Signature verification failure
`200E3`	System busy, please try again later
`200N0`	Force STIP
`200N7`	Decline for CVV2 failure
`200O5`	PIN required
`200P1`	Over daily limit
`200P9`	Limit exceeded. Enter a lesser value.
`200R1`	Issuer initiated a stop payment (revocation order) for this authorization	The cardholder has canceled this subscription
`200R3`	Issuer initiated a stop payment (revocation order) for all authorizations	The cardholder has canceled all subscriptions
`200S4`	PTLF full
`200T2`	Invalid transaction date
`200T3`	Card not supported
`200T5`	CAF status = 0 or 9
`20100`	Invalid expiry date format	The payment failed due to invalid expiry date. Please try again providing the correct value.
`20101`	No Account / No Customer (Token is incorrect or invalid)
`20102`	Invalid merchant / wallet ID	The payment failed due to a technical issue. If the issue persists please contact us.
`20103`	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.
`20104`	Gateway reject - Invalid transaction	The payment failed due to a technical issue. Please try again with the same card, or use a different card.
`20105`	Gateway reject - Violation	The payment failed due to a technical issue. Please try again with the same card, or use a different card.
`20106`	Unsupported currency
`20107`	Billing address is missing
`20108`	Declined - Updated cardholder available
`20109`	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
`20110`	Authorization completed
`20111`	Transaction already reversed	The payment reversal has already been processed.
`20112`	Merchant not Mastercard SecureCode enabled	The payment failed due to a technical issue. Please contact us with the payment reference number.
`20113`	Invalid property
`20114`	Token is incorrect
`20115`	Missing / Invalid lifetime
`20116`	Invalid encoding
`20117`	Invalid API version	The payment failed due to a technical issue. If the issue persists please contact us.
`20118`	Transaction pending	The payment failed due to a technical issue. If the issue persists please contact us.
`20119`	Invalid batch data and/or batch data is missing	The payment failed due to a technical issue. If the issue persists please contact us.
`20120`	Invalid customer/user	The payment failed due to a technical issue. If the issue persists please contact us.
`20121`	Transaction limit for merchant/terminal exceeded
`20122`	Mastercard installments not supported
`20123`	Missing basic data: zip, addr, member	The payment failed due to a technical issue. If the issue persists please contact us.
`20124`	Missing CVV value, required for ecommerce transaction
`20150`	Card not 3D Secure (3DS) enabled
`20151`	Cardholder failed 3DS authentication
`20152`	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.
`20153`	3DS system malfunction	The payment failed due to a technical issue. Please try again with the same card, or use a different card.
`20154`	3DS authentication required	The payment declined due to Strong Customer Authentication (3DS). Please try again with the same card, or use a different card.
`20155`	3DS authentication service provided invalid authentication result
`20156`	Requested function not supported by the acquirer
`20157`	Invalid merchant configurations - Contact Support
`20158`	Refund validity period has expired
`20159`	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.
`20179`	Lifecycle	Occurs when transaction has invalid card data. Refer to the page on recommendation codes for suggested action.
`20182`	Policy	Occurs when a transaction does not comply with card policy. Refer to the page on recommendation codes for suggested action.
`20183`	Security	Occurs when a transaction is suspected to be fraudulent. Refer to the page on recommendation codes for suggested action.
`20193`	Invalid country code

Information

The response code message text may vary across different endpoint responses.

Response code	Response text	Additional information
`30004`	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.
`30007`	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.
`30015`	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.
`30016`	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.
`30017`	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.
`30018`	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.
`30019`	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.
`30020`	Invalid amount	The payment failed due to a technical issue. If the issue persists please contact us.
`30021`	Total amount limit reached	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`30022`	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.
`30033`	Expired card - Pick up	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`30034`	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.
`30035`	Contact acquirer - Pick up	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`30036`	Restricted card - Pick up	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`30037`	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.
`30038`	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.
`30041`	Lost card - Pick up	The payment has been declined by your bank. Please try a different card or contact your bank for further support.
`30043`	Stolen card - Pick up	The cardholder’s bank has declined the payment because the card has been reported stolen. For a one-off transaction, do not attempt the transaction again. If possible, do not provide goods or services to the person attempting the transaction. For a recurring or scheduled transaction, it's possible the card was lost after the last successfully processed payment, or after the scheduled payment's authorization. In either scenario, contact your customer and request that they update their payment method. Replace the account number for their lost card with the account number for their new card.
`30044`	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.
`30045`	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.
`30046`	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
`40101`	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.
`40201`	Gateway reject - card number blocklist
`40202`	Gateway reject - IP address blocklist
`40203`	Gateway reject - email blocklist
`40204`	Gateway reject - phone number blocklist
`40205`	Gateway Reject - BIN number blocklist

Information

The response code message text may vary across different endpoint responses.

Response code	Response text	Additional information
`50001`	Compliance error
`50002`	Sanction screening failure	Sanctions screening hit or data corruption.
`50003`	Balance reservation insufficient funds	Insufficient available balance in sub-account.
`50005`	Barred Beneficiary Error
`50020`	Recipient error
`50021`	Invalid recipient error
`50022`	Unsupported recipient error
`50023`	Recipient limit error
`50025`	Invalid Recipient Account Error
`50026`	Recipient Account Not Found
`50027`	Recipient Bank Error
`50030`	Invalid Recipient Details Error
`50070`	Sender error
`50100`	Instruction error
`50101`	Instruction amount limit error
`50102`	Instruction amount limit sender error
`50103`	Instruction amount limit recipient error
`50104`	Velocity limit
`50105`	Velocity limit sender error
`50106`	Velocity limit recipient limit error
`50150`	Processing error
`50180`	Validation error
`50200`	Configuration error
`50240`	Cancellation error
`50260`	Returned error
`50280`	Insufficient funds
`50399`	Unmapped response
`50401`	Bank details invalid
`50402`	Account not found
`50403`	Account inactive
`50404`	Account dormant
`50405`	Account number invalid
`50406`	Branch not found
`50407`	Branch code invalid
`50408`	Branch code required
`50409`	Bank code invalid
`50410`	Bank code required
`50441`	Account type required
`50451`	Account holder details invalid
`50452`	Account holder identification number required
`50453`	Account holder type not supported
`50454`	Account holder type not allowed
`50466`	Account closed
`50471`	Account blocked
`50481`	Invalid debtor account type
`50490`	Duplicate Payment
`50491`	Account holder billing address details incorrect
`50492`	Account holder billing address details required
`50494`	Account holder billing address can not be PO box
`50499`	Payout Returned
`50501`	Unsupported characters
`50511`	Invalid amount
`50512`	Minimum amount not met
`50513`	Exceeded transaction value
`50514`	Exceeded daily limit
`50515`	Exceeded weekly limit
`50517`	Exceeded monthly limit
`50531`	Recalled
`50599`	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:

the
post
Request a payment response
the
get
Get payment details response
webhook notifications

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  "response_code": "20051",
3  "response_summary": "Insufficient funds",
4  "processing":  {
5    "scheme": "mastercard",
6    "partner_response_code": "51"
7  }
8}


1{
2  "response_code": "20051",
3  "response_summary": "Insufficient funds",
4  "processing":  {
5    "scheme": "amex",
6    "partner_response_code": "116"
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": false
19  },
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
`200`	OK
`201`	Created
`202`	Accepted
`401`	Unauthorized
`403`	Not allowed
`404`	Not found
`409`	Conflict with another request being processed
`422`	Invalid data was sent
`429`	Too many requests
`500`	Internal server error
`502`	Bad gateway

API response codes

Information

Response code ranges

10xxx - APPROVED

Information

20xxx - SOFT DECLINE

Information

30xxx - HARD DECLINE

Information

40xxx - RISK RESPONSES

Information

50xxx - CHECKOUT.COM DECLINE

Information

Declined - Do not honour

Trigger scenarios

Resolving the response

Raw response codes (Beta)

Information

Payment response example

Webhook example

HTTP status codes