Issuing decline reasons

Last updated: May 31, 2023

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

Card errors typically occur due to the card's status. In some instances, 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.	No further action can be taken on a revoked 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.

PIN errors can typically be resolved by the cardholder attempting the transaction or PIN change action again.

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 should 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 should attempt to change the PIN again.
`pin_change_failed`	The online PIN change attempt failed, or there was an error when attempting to cancel the PIN change.	If the cardholder attempts an online PIN change again and it fails, contact Checkout.com.
`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.

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 Checkout.com.
`user_authentication_amount_mismatched`	Authentication failed due to the authorization and authentication amounts not matching.	Review the authorization and authentication amounts provided in the payment request.
`user_authentication_currency_mismatched`	Authentication failed due to the authorization and authentication currencies not matching.	Review the authorization and authentication currencies provided in the payment request.
`user_authentication_verification_failed`	Cardholder authentication failed due to an invalid ecommerce cryptogram.	No further action available.
`user_authentication_verification_unavailable`	The card scheme was unable to authenticate the transaction at the user authentication stage.	No further action available.

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

Decline reason	Description	Recommended action
`card_control_failed`	There was an error with the card's controls. Rules from different controls may be conflicting.	Review the card's 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 the card's controls.	To allow transactions for the blocked MCC, update the card's controls.
`velocity_reached`	The transaction amount exceeded the card's velocity limit.	If the cardholder requires a higher velocity limit, update the card's controls.

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`	The authorization relay request was declined by the client's authorization relay server due to insufficient funds, or an invalid transaction.	No further action available.
`authorization_relay_error`	The authorization relay request was sent, but the client was unreachable.	Attempt the authorization relay request again. If the error persists, contact Checkout.com.
`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`	The client's authorization relay server timed out during an authorization relay request.	The cardholder can attempt the transaction again.

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 due to the authorization and authentication amounts not matching.	No further action 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_transaction_analysis_declined`	The transaction was declined on the card scheme's recommendation.	No further action available.
`wallet_type_unsupported`	Card tokenization was attempted from a digital wallet other than Apple Pay or Google Pay.	Contact Checkout.com.

Card scheme errors typically occur due to the card scheme declining 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 available.

Authorization errors typically occur when there are problems with the information provided during a transaction's authorization.

Decline reason	Description	Recommended action
`account_currency_mismatched`	Reversal failed due to the billing and card's currency account currencies not matching.	No further action available.
`balance_verification_failed`	An internal balance control failed.	No further action 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 CVC1 or service code received was incorrect, so the payment was declined.	Contact Checkout.com.
`cvc2_invalid`	An incorrect CVC2 was provided in a card-not-present (CNP) transaction.	Validate the CVC2.
`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 Checkout.com.
`insufficient_funds`	The amount required to complete the transaction is higher than the funds available in the card's currency account.	Add funds to your currency account.
`low_value_payment_amount_failed`	A low value payment transaction was attempted, but the authorization amount exceeded the low value payment limit.	Attempt the transaction again, with SCA.
`low_value_payment_count_failed`	Too many low value payment transactions were attempted with the card, over a short period of time.	Attempt the transaction again, with SCA.
`original_transaction_not_found`	A reversal was attempted, but the original authorization could not be found.	No further action available.
`partial_reversal_amount_invalid`	A partial reversal was attempted, but the reversal amount exceeded the authorization amount.	No further action available.
`reversal_currency_mismatched`	Reversal failed due to the reversal and authorization currencies not matching.	No further action available.
`reversal_exceeds_authorized_amount`	The reversal amount exceeded the pending authorization amount.	No further action available.
`system_malfunction`	There was a failure with Checkout.com systems.	The frequency of this error is monitored and automatically triggers investigation if a high number of occurrences is detected. If the issue persists, contact Checkout.com.
`three_d_secure_soft_declined`	SCA was required for the transaction, but no 3DS challenge was attempted.	No further action available.
`state_or_country_invalid`	The country code or state provided by the merchant was invalid.	No further action available.
`transaction_not_permitted_to_cardholder`	The transaction attempted is not supported by the issuer, or the specific card used.	No further action available.