Error & Status Codes

Reference for order phase/status values and normalized payment error codes

Crossmint checkout exposes status codes for multiple aspects of the order. There is the top-level order.phase, and then sub-statuses for quote, payment, and delivery. Use them to build UIs that inform buyers where their order is in the payment and delivery process.

​

Quote Statuses

• item-unavailable — No items in the order are available for purchase at the current time
• valid — The quote is valid
• expired — The quote has expired and needs to be refreshed
• requires-recipient — The order is missing recipient information (email or wallet address)

​

Payment Statuses

• draft — The order was created with state: "draft". It is a quote preview only: not persisted, and it cannot be polled or paid
• requires-quote — The order is still in the quote phase
• requires-crypto-payer-address — A crypto wallet address needs to be provided for the payment
• requires-email — An email is required to proceed (typically for card payments or receipts)
• requires-kyc — The buyer must complete KYC verification to proceed
• manual-kyc — KYC requires manual review; the buyer will be notified of the outcome
• failed-kyc — KYC verification failed and the buyer cannot proceed
• crypto-payer-insufficient-funds — The specified payer address cannot cover the purchase
• crypto-payer-insufficient-funds-for-gas — The payer address cannot cover the required network fees
• awaiting-payment — Ready to submit the payment
• in-progress — The payment is underway
• completed — Payment completed; the order proceeds to delivery/completion

When a card payment is declined, the order also carries a payment.failureReason object with a normalized error code, category, and retry policy — see the Payment Error Codes section below.

​

Delivery Statuses

• draft — The order is a draft (state: "draft"); nothing will be delivered until the order is created for real
• awaiting-payment — Delivery not started because payment is not yet complete
• in-progress — Delivery is being processed
• failed — Delivery failed; affected items will be refunded automatically
• completed — Delivery completed successfully

​

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."
        }
    }
}

A card decline returns the order to awaiting-payment regardless of the decline code, so the order status only tells you that the order can still accept a payment. Use retryPolicy to decide whether to offer a retry: an order can be awaiting-payment with retryPolicy: "do_not_retry" (for example psp_security_block), which means the order is open but you should not offer a retry. Never retry a declined payment automatically on the buyer's behalf.

​

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.
card_holder_name_mismatch	The cardholder name does not match the buyer's verified identity. Ask the buyer to pay with a card issued in the same name as their verified identity.
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.

​

See Also

Handle Errors

Surface decline reasons and delivery failures in your checkout UI

Track Orders

Poll order status or receive webhook events