Payment Error Codes

Learn how to identify payment errors and guide buyers toward the right next step. When a payment fails, Crossmint returns a normalized error category and code in the order's payment.failureReason. Use the category to understand the general cause and the code to determine how your integration should handle the error. You can review payment failures in the Orders section of the Crossmint Console. The tables below describe each error code, what it means, and the action you should present to the buyer.

Payment error codes describe why a payment attempt was declined. They are different from order status codes, which describe where an order is in its lifecycle (quote, payment, and delivery statuses). A declined payment usually returns the order to the awaiting-payment status so the buyer can retry.

The `failureReason` Object

Field	Type	Description
`category`	`string` (optional)	The broad reason the payment failed. One of the six error categories below. Use it for grouping, analytics, and coarse UI branching.
`code`	`string`	The specific normalized error. Stable across payment methods and underlying providers. Use it for logic, analytics, and support tooling.
`message`	`string` (optional)	User-safe explanation of the decline. The only field intended to be rendered to buyers.
`retryPolicy`	`string` (optional)	Machine-readable hint for the next step: `complete_authentication`, `contact_payment_provider`, `do_not_retry`, `retry_after_cooldown`, `retry_with_different_payment_method`, or `review_payment_information`. The guidance for each code below already reflects its retry policy.

category, retryPolicy, and message are present when Crossmint recognizes the decline. When a decline cannot be normalized, code is unknown (or the raw code when one is available) and only code and message are returned.

{
    "payment": {
        "status": "awaiting-payment",
        "failureReason": {
            "code": "insufficient_funds",
            "category": "authorization_decline",
            "retryPolicy": "contact_payment_provider",
            "message": "Your card has insufficient funds to cover this transaction. Please use a different payment method or add funds to your account and try again."
        }
    }
}

Never retry a declined payment automatically on the buyer's behalf, and gate any retry affordance on the order returning to the awaiting-payment status. Some declines are terminal and leave the order in a failed state.

Error Categories

`category`	Meaning
`verification_error`	A required verification or authentication step failed or was not completed — 3DS authentication, or validation of the card, identity, billing, or network details.
`transactional_limits`	The payment exceeds a transaction or usage limit, such as a maximum amount, transaction count, or velocity threshold within a defined period.
`policy_restrictions`	The payment violates a payment policy or restriction, such as regional availability, unsupported card types, or unsupported issuers.
`risk_block`	Crossmint, a payment partner, or the buyer's bank blocked the payment because of a fraud or risk decision.
`authorization_decline`	The buyer's financial institution declined the authorization attempt — for example insufficient funds, an unsupported currency, or an issuer-specific restriction.
`processing_error`	A technical problem prevented the payment from completing. The failure was not caused by a risk decision or an authorization decline.

Verification Errors

Category value: verification_error The payment could not be completed because a required verification or authentication step failed or was not completed. This includes 3DS authentication and validation of the card details, identity, billing information, or network connection. Most of these declines are resolved by the buyer correcting the information or completing the authentication step, so keep the buyer on the checkout and let them retry.

Error code	Description
`authentication_required`	The buyer's bank requires an additional authentication step (3DS or strong customer authentication) before approving the payment. Prompt the buyer to complete the verification requested by their bank and retry the same card. If authentication was completed and this code persists, ask the buyer to contact their bank or use a different payment method.
`billing_verification_failed`	The name, billing address, or postal code provided does not match the records held by the buyer's bank or identity verification provider. Prompt the buyer to review their payment information. If they are paying with Apple Pay or Google Pay, ask them to check the billing address saved in their device settings. Buyers who recently moved may need to contact support.
`closed_account`	The buyer's bank reports that the card or account is closed or blocked. Retrying the same card will fail again; ask the buyer to use a different card or payment method.
`expired_account`	The card or account has expired. Ask the buyer to use a different card or payment method. If they are paying with Apple Pay or Google Pay, ask them to update or remove the expired card in their wallet.
`invalid_account`	The card or account number is invalid or was entered incorrectly. Prompt the buyer to re-enter the card number and retry.
`invalid_amount`	The payment amount is not accepted — zero, negative, below the minimum, or above the maximum allowed for the buyer's account. Ask the buyer to contact their bank about the limit or use a different payment method.
`invalid_expiry_date`	The expiration month or year is invalid or does not match the card. Prompt the buyer to re-enter the expiration date and retry.
`invalid_security_code`	The card's security code (CVC/CVV) does not match the card. Prompt the buyer to re-enter the security code and retry.
`invalid_token`	The payment session or payment token is invalid or has expired, typically because the buyer left the checkout open for too long. Restart the payment so a new token is generated, then ask the buyer to try again.
`network_verification_failed`	The buyer's network connection could not be verified, typically because a VPN or proxy makes the connection appear to come from a different country than the card. Ask the buyer to disable the VPN or proxy and retry the same card.

Transactional Limits

Category value: transactional_limits The payment exceeds a transaction or usage limit, such as the maximum amount, transaction count, or velocity threshold within a defined period. The limit may be set by Crossmint or by the buyer's bank. Do not retry automatically; the buyer can try again after the cooldown.

Error code	Description
`issuer_limit_exceeded`	The buyer's bank declined the payment because a spending or transaction-count limit on the card was exceeded. Ask the buyer to try again later, contact their bank to raise the limit, or use a different card.
`payment_limit_exceeded`	The buyer made too many payment attempts in a short period. Tell the buyer to wait and try again in 1 hour with the same payment method. Do not prompt for a different card, because the limit applies to the buyer rather than the card.

Policy Restrictions

Category value: policy_restrictions The payment violates a payment policy or restriction, such as regional availability, unsupported card types, or unsupported issuers. Depending on the code, the buyer may be able to complete the purchase with a different payment method.

Error code	Description
`card_issuer_not_supported`	Cards from the buyer's issuing bank are not accepted for this purchase. Ask the buyer to use a card from a different bank or another payment method.
`card_type_not_supported`	The card type is not accepted. Prepaid cards are not supported. Ask the buyer to use a debit or credit card instead. If they are paying with Apple Pay or Google Pay, ask them to select a different card in the wallet.
`region_not_supported`	The purchase is not available in the buyer's country or region. This is final for the buyer: do not offer a retry or prompt for another payment method. Show a clear message that the item cannot be purchased from their location.

Risk Blocks

Category value: risk_block Crossmint, a payment partner, or the buyer's bank blocked the payment because of a fraud or risk decision. These declines are intentionally generic: the message never reveals why the payment was flagged, and your integration should not attempt to infer or display a reason beyond the user-safe message. Do not retry automatically. Direct buyers who believe the block is a mistake to your support channel.

Error code	Description
`crossmint_security_block`	Crossmint blocked the payment as a result of a risk decision. Do not offer a retry. Tell the buyer the payment could not be completed and to contact support if they believe this is an error.
`issuer_security_block`	The buyer's bank declined the payment for security reasons, for example because the card was reported lost or stolen or the bank flagged the transaction. Do not retry the same card; ask the buyer to contact their bank.
`psp_security_block`	A payment partner blocked the payment as a result of a risk decision. Do not offer a retry. Tell the buyer the payment could not be completed and to contact support if they believe this is an error.

Authorization Declines

Category value: authorization_decline The buyer's financial institution declined the authorization attempt. Examples include insufficient funds, an unsupported currency, or an issuer-specific restriction. In most cases the buyer must contact their bank or use a different payment method; do not retry automatically.

Error code	Description
`card_not_retryable`	The payment was stopped before reaching the buyer's bank because the card was unlikely to be authorized. Retrying the same card will fail again; ask the buyer to use a different card or payment method.
`generic_decline`	The buyer's bank declined the payment without providing a specific reason. Ask the buyer to contact their bank to authorize the purchase, or to try a different payment method.
`insufficient_funds`	The card balance or credit limit is insufficient for the payment amount. Ask the buyer to add funds, use a different card, or choose another payment method.
`issuer_decline`	The buyer's bank declined the payment. Common causes are account restrictions or a card that does not support this type of purchase (for example, cards blocked for online or cross-border transactions). Ask the buyer to contact their bank to authorize the purchase or use a different card.
`unsupported_currency`	The buyer's card or account does not support payments in the requested currency. Ask the buyer to use a card that supports international or multi-currency payments, or another payment method.

Processing Errors

Category value: processing_error A technical or processing problem prevented the payment from completing. The failure was not caused by a risk decision or authorization decline, and a retry after a short delay usually succeeds.

Error code	Description
`duplicate_transaction`	A payment with the same amount and card details was submitted within a very short window. Check whether a charge already exists for the order before allowing another attempt, and ask the buyer to review their recent transactions before retrying.
`processing_error`	The bank or a payment partner experienced a temporary technical issue (communication failure, routing issue, or timeout). Ask the buyer to try again after a few seconds with the same payment method. If the error persists, ask them to contact their bank or your support.

Display Payment Error Messages

Surface the decline reason in Embedded Checkout, including after the Apple Pay or Google Pay sheet closes

Supporting Your Customers

What to collect from a buyer before escalating a checkout issue to Crossmint

Status Codes

Order, quote, payment, and delivery statuses, which are distinct from payment error codes

Pay with Card

The payment phase of the Headless Checkout order lifecycle, including handling declined payments

Get Order

REST endpoint that returns the order, including payment.failureReason

Webhooks

Receive order updates, including declines, server-side

Introduction

Hosted (pop-up)

Embedded

Headless (API)

Advanced Guides

API Reference

The `failureReason` Object

Error Categories

Verification Errors

Transactional Limits

Policy Restrictions

Risk Blocks

Authorization Declines

Processing Errors

See Also

Display Payment Error Messages

Supporting Your Customers

Status Codes

Pay with Card

Get Order

Webhooks

​The failureReason Object

​Error Categories

​Verification Errors

​Transactional Limits

​Policy Restrictions

​Risk Blocks

​Authorization Declines

​Processing Errors

​See Also

Display Payment Error Messages

Supporting Your Customers

Status Codes

Pay with Card

Get Order

Webhooks

The `failureReason` Object

Error Categories

Verification Errors

Transactional Limits

Policy Restrictions

Risk Blocks

Authorization Declines

Processing Errors

See Also