Issuing decline codes

Last updated: September 11, 2024

If a transaction performed by a card you issued fails, you may receive an authorization_declined or reversal_declined webhook. The webhook response contains a decline_reason field with one of the values listed on this page.

Authentication errors occur when the card or user cannot be authenticated.

Decline reason	Description	Recommended action
`card_authentication_failed`	There was a problem with the physical card, and it may need to be replaced.	Contact your Account Manager.
`contactless_counter_limit_reached`	The number of consecutive unauthenticated contactless transactions on the card has exceeded the threshold. This threshold is set to protect the card from potential fraud.	Before using contactless again, the cardholder must make a Chip and PIN transaction with the card.
`contactless_accumulator_limit_reached`	The cumulative cardholder billing amount for unauthenticated contactless transactions on the card has exceeded the threshold.	The cardholder must enter their PIN on the terminal when prompted to complete the transaction. Alternatively, the cardholder can perform another transaction and authenticate with their PIN.
`contactless_amount_threshold_exceeded`	The contactless transaction was declined because the amount exceeds the limit for the country it was performed in.	The cardholder must perform a Chip and PIN transaction instead.
`user_authentication_amount_mismatched`	Authentication failed because the authorization and authentication amounts did not match.	Review the authorization and authentication amounts provided in the payment request.
`user_authentication_currency_mismatched`	Authentication failed because the authorization and authentication amounts did not match.	Review the authorization and authentication currencies provided in the payment request.
`user_authentication_verification_failed`	Authentication failed because of an issue with the merchant's configuration - `ecommerce cryptogram invalid`	No further action is available.
`user_authentication_verification_unavailable`	The card scheme was unable to authenticate the transaction at the user authentication stage.	No further action is available.
`original_transaction_not_authenticated`	A recurring or a merchant-initiated transaction was attempted, but the original transaction was not strongly authenticated.	No further action is available.

Authorization errors typically occur when there are problems with the information provided when authorizing a transaction.

Decline reason	Description	Recommended action
`account_currency_mismatched`	Reversal failed because the billing and card sub-account currencies did not match.	No further action is available.
`balance_verification_failed`	An internal balance control failed.	No further action is available.
`billing_amount_threshold_exceeded`	The transaction amount exceeded the limit allowed for non-Strong Customer Authentication (SCA) transactions.	Attempt the transaction again later.
`card_data_verification_failed`	The card could not be verified because the CVV or service code received was incorrect, so the payment was declined.	Contact your Account Manager.
`cvc2_invalid`	An incorrect CVV was provided in a card-not-present (CNP) transaction.	Validate the CVV.
`expiry_date_invalid`	An incorrect card expiry date was provided in a card-not-present (CNP) transaction.	Validate the card's expiry date. If this error is received from a physical card, replace the card, or contact your Account Manager.
`insufficient_funds`	The amount required to complete the transaction is higher than the funds available in the card's sub-account.	Add funds to your sub-account.
`low_value_payment_amount_failed`	A low-value payment transaction was attempted, but the authorization amount exceeded the low-value payment limit.	The cardholder must reattempt the transaction with 3D Secure.
`low_value_payment_count_failed`	Too many low-value payment transactions were attempted with the card within a short period of time.	The cardholder must reattempt the transaction with 3D Secure.
`original_transaction_not_found`	A reversal, recurring transaction, or merchant-initiated transaction was attempted, but the original transaction could not be found.	No further action is available.
`partial_reversal_amount_invalid`	A partial reversal was attempted, but the reversal amount exceeded the authorization amount.	No further action is available.
`reversal_currency_mismatched`	Reversal failed because the reversal and authorization currencies did not match.	No further action is available.
`reversal_exceeds_authorized_amount`	The reversal amount exceeded the pending authorization amount.	No further action is available.
`system_malfunction`	There was a failure with Checkout.com systems.	Checkout.com monitors the frequency of this error and automatically triggers an investigation if we detect a high number of occurrences. If the issue persists, contact your Account Manager.
`three_d_secure_soft_declined`	Strong Customer Authentication (SCA) was required for the transaction, but no 3D Secure challenge was attempted.	The cardholder must reattempt the transaction with 3D Secure.
`state_or_country_invalid`	The country code or state the merchant provided was invalid.	No further action is available.
`transaction_not_permitted_to_cardholder`	The type of transaction attempted is not supported by Checkout.com, or has been disabled for the card.	Contact your Account Manager.

Authorization relay errors typically occur due to issues with the authorization relay service integration, or client-server communication.

Decline reason	Description	Recommended action
`authorization_relay_declined`	Your authorization relay server declined the authorization relay request.	If this payment should have been approved, review your authorization logic configuration.
`authorization_relay_error`	The authorization relay request was sent, but your server was unreachable.	Reattempt the authorization relay request. If the error persists, contact your Account Manager.
`authorization_relay_response_invalid`	The authorization relay response received from the client was invalid, likely due to a formatting issue.	Review your client-side authorization relay service integration for formatting issues.
`authorization_relay_timed_out`	Your authorization relay server timed out during an authorization relay request.	Reattempt the authorization relay request. If the error persists, contact your Account Manager.

Card control errors occur when a transaction conflicts with the spending controls you applied to the card.

Decline reason	Description	Recommended action
`card_control_failed`	There was an error with the spending controls. Rules from different controls may be conflicting.	Review the spending controls using the Dashboard or API, and update them as required.
`merchant_category_not_allowed`	A transaction was attempted for a merchant category code (MCC) that is blocked by your spending controls.	To allow transactions for the blocked MCC, update your spending controls.
`merchant_not_allowed`	A transaction was attempted for a merchant ID (MID) that is blocked by your spending controls.	To allow transactions for the blocked MID, update your spending controls.
`velocity_reached`	The transaction amount exceeded the card's velocity limit.	If the cardholder requires a higher velocity limit, update your spending controls.
`merchant_identifier_not_allowed`	A transaction was attempted for a merchant ID (MID) that is blocked by your spending controls.	To allow transactions for the blocked MID, update your spending controls.

Card errors typically occur due to the card's status. You may be able to resolve the problem by updating the card status.

Decline reason	Description	Recommended action
`card_expired`	The card has expired. All authorizations will be declined, permanently.	To allow the cardholder to continue to perform transactions, issue them with a replacement card.
`card_inactive`	The card has not been activated. All authorizations will be declined.	To allow transactions, activate the card.
`card_revoked`	The card has been revoked. All authorizations will be declined, permanently.	To enable the cardholder to continue performing transactions, issue them with a replacement card.
`card_suspended`	The card has been suspended. All authorizations will be declined.	To allow transactions, activate the card. Alternatively, to permanently block all transactions, revoke the card.

Card scheme errors typically occur because the card scheme declined the transaction. In some instances, attempting authentication at a later time may resolve the problem.

Decline reason	Description	Recommended action
`scheme_fraud_score_missing`	The card scheme authentication failed due to a missing fraud score.	Attempt authentication again later.
`scheme_fraud_score_threshold_exceeded`	The card scheme blocked the transaction, and may suspect fraud.	Attempt authentication again later.
`scheme_merchant_data_validation_failed`	The merchant information supplied during authentication and authorization did not match.	No further action is available.

Digital wallet errors typically occur due to a digital card's status, or issues with authentication. If the card status is the cause, you may be able to resolve this by updating the card status.

Decline reason	Description	Recommended action
`amount_invalid`	Authentication failed because the authorization and authentication amounts did not match.	No further action is available.
`digital_card_deleted`	The digital card has been deleted and no longer exists in the digital wallet.	Check if you, or the cardholder, have previously revoked the card. If the card is not revoked, add it to the digital wallet again. Otherwise, no further action is available.
`digital_card_expired`	The card has expired. All authorizations will be declined, permanently.	To allow the cardholder to continue to perform transactions, issue them with a replacement card.
`digital_card_inactive`	The digital card has been deactivated in the digital wallet. All authorizations will be declined.	Check if you, or the cardholder, have previously suspended the card and reactivate if necessary.
`digital_card_not_found`	The digital card has not been found in the system.	No further action is available.
`digital_card_transaction_analysis_declined`	The transaction was declined on the card scheme's recommendation.	No further action is available.
`wallet_type_unsupported`	Card tokenization was attempted from a digital wallet other than Apple Pay or Google Pay.	Contact your Account Manager.

PIN errors can typically be resolved by the cardholder reattempting the transaction or changing their PIN.

Decline reason	Description	Recommended action
`contactless_pin_change_not_allowed`	A physical card PIN change was attempted without inserting the card into the ATM.	The cardholder must insert the card and attempt the PIN change again, or use a different ATM.
`new_pin_data_not_received`	A PIN change was attempted, but the new PIN was not received successfully.	The cardholder must attempt to change the PIN again.
`pin_change_failed`	An online PIN change attempt failed, or there was an error when attempting to cancel it.	If the cardholder attempts an online PIN change again and it fails, contact your Account Manager.
`pin_invalid`	The PIN provided during the point-of-sale (POS) transaction was invalid, or incorrect.	If the cardholder attempts the transaction again, validate the PIN.