Card payments can fail for a variety of reasons. Understanding why declines occur and how to respond to them helps improve payment success rates, reduce customer friction, and ensure compliant retry behavior.

What Is a Card Decline?

When a card payment is attempted, the card issuer evaluates the request using automated systems and risk models. These systems analyse signals such as:

Spending behaviour and transaction patterns
Available balance or credit limit
Card details (expiry date, CVC, address)
Potential fraud indicators

If the issuer decides not to approve the transaction, the payment is declined. Passport communicates this outcome through the API using decline codes and advisory messages.

Common Reasons for Card Declines

When a transaction is declined, Passport returns details in the API response.

Decline Codes

Issuers sometimes provide specific decline reasons (for example, incorrect card number or low funds).
Many declines are categorised as generic, such as General declines or Do not honour, where the exact reason is not disclosed.

Please refer to the complete list of Decline codes under the Decline tab on Payment Response Code page.

For privacy and security reasons, issuers share detailed explanations only with the cardholder.

Decline Reason	Recommended Action
Insufficient funds	Ask the customer to use a different card or an alternative payment method.
Incorrect card details i.e. card number, expiry date, or CVC	Prompt the customer to re-enter their card number, expiry date, and CVC carefully.
Suspected fraudulent activity such as Large purchase amounts, multiple transactions in a short time, or unusual spending behaviour	Advise the customer to contact their card issuer to verify the transaction and confirm their identity.
Generic issuer decline (`generic_decline`, `do_not_honor`)	If card details are correct, ask the customer to contact their card issuer for more information.
Failed CVC or AVS checks	Request the customer to verify their CVC and billing address before retrying the payment.
Card type built-in restrictions, for example, FSA/HSA cards, or cards are blocked for international or cross-border usage	Inform the customer that their card may be restricted and advise contacting the card issuer.
Cross-border or country restrictions	Ask the customer to check with their card issuer about international or regional usage restrictions.
Retry limit exceeded	Do not retry the transaction. Ask the customer to use a different payment method.

Outcome Fields You Should Review

When a transaction is declined, the payment response includes structured outcome details from the card network and issuer. These fields explain why the authorization failed and provide guidance on whether and how the transaction should be retried. Reviewing these fields carefully helps you determine the appropriate next action and avoid unnecessary retries that could increase future decline rates.

Field	Purpose
`authMessage`	High-level message describing the outcome
`responseCode`	Decline code indicating why the authorization failed
`merchantAdviceCode`	Recommended next action
`merchantAdviceMessage`	Human-readable guidance

Merchant Advice Codes and Recommended Actions

Merchant Advice Codes provide issuer-recommended guidance on how to proceed after a transaction is declined. These codes indicate whether a payment can be retried, requires corrected customer information, or should not be attempted again.

Always follow the recommended action to reduce unnecessary retries, prevent fraud-related flags, and improve future authorization success rates.

Advice Code	Description	Recommended Next Steps
`do_not_try_again`	The card was declined and should not be retried	Review the decline code. Ask the customer to contact their card issuer or use a different payment method.
`try_again_later`	The transaction can be retried	Ask the customer to attempt the payment again. If repeated declines occur, advise contacting the issuer.
`confirm_card_data`	Incorrect card information was provided	Ask the customer to verify and re-enter card details before retrying.

Best Practices to Reduce Card Declines

You can proactively reduce declines by following these best practices:

Always request CVC and postal code during checkout
Validate card details before submitting a charge
Monitor AVS and CVC check results
Prompt customers to correct failed verification data
Provide clear, actionable error messages during checkout

Managing Declines Based on Customer Presence

On-Session Declines (Customer Present)

When the customer is actively in the checkout flow:

Prompt the customer to retry the payment
Request corrected or verified card details
Allow selection of an alternative payment method

Off-Session Declines (Customer Not Present)

When the customer is not actively engaged:

Notify the customer via email or in-app message
Provide a secure path to update their payment method
Retry the payment only when permitted by the merchant advice code

Retry Guidelines and Network Limits

Card networks limit how many times a charge can be retried.

Best practice:

Do not exceed 8 retries for charges that allow retries
Avoid rapid or excessive retries, as issuers may flag them as potential fraud
Excessive retries can increase decline rates for legitimate transactions.