Decline codes

When a card payment fails, the failed charge carries a decline code describing why. Frame normalizes the raw codes from card networks and issuing banks into a developer-friendly enum — so you don't have to learn dozens of issuer-specific strings to know whether to prompt the customer to retry or surface a generic error.

The decline code lives on the failure_code field of the underlying Charge record (which the transfer wraps). The parent Transfer carries a more general failure_reason string that points at the broader failure category. For programmatic handling of decline scenarios, read the Charge's failure_code and branch on the categorical reason.

Soft vs hard declines

The first cut on every decline code: was the failure transient (try again, maybe with a tweak) or permanent (this card isn't going to work)?

• Soft decline — temporary, retryable. Insufficient funds, issuer reachability problems, requires 3D Secure authentication. The customer can take an action (top up the card, complete an authentication step) and a retry may succeed.
• Hard decline — permanent, do not retry. Stolen card, fraud, expired card, invalid account. The customer needs to use a different payment method.

Frame's recommended response for each code is summarized in the table below, but the merchant judgement is: soft codes are worth one retry attempt with appropriate UX; hard codes should immediately route the customer to a different payment method.

Categories worth knowing

Behind the long enum is a smaller set of categories that drive the right merchant response:

The merchant rule of thumb: anything in the "fraud / risk signal" row should be surfaced to the customer as a generic error. Telling the customer "your card was reported stolen" is bad for two reasons: it's customer-hostile (they may not know, and your platform isn't the right place to find out), and it tips off actual fraudsters about which signals tripped them.

Full code list

The complete enum, with Frame's recommended next step:

Customer-facing display

When a decline involves fraud or card-loss signals (fraudulent, lost_card, stolen_card, pickup_card, merchant_blacklist, restricted_card), always show the customer a generic error message like "We couldn't process your card. Please try a different payment method." Don't expose the underlying decline code or its specific reason. Two reasons:

1. Customer experience — telling a customer their card is reported stolen via your checkout flow is harsh and likely wrong context (they may not know yet, or the report may be erroneous).
2. Fraud prevention — fraudsters use decline reasons to learn which signals to evade. Generic errors are slightly more friction for them.

For all other decline codes, the description is safe to surface directly — "insufficient funds," "invalid CVC," "card expired" — these help the customer understand what to fix.

Reading the code

Decline codes appear on the underlying Charge record (which the failed transfer wraps):

{
  "id": "charge_...",
  "status": "failed",
  "failure_code": "insufficient_funds",
  "failure_message": "Your card has insufficient funds."
}

The parent Transfer surfaces a coarser failure_reason string for general categorization; the Charge's failure_code is the specific normalized decline.

Listen for transfer.failed and charge.failed webhook events to react to declines in real time. The payload references both the transfer and the parent charge so you can pull failure_code from the latter without an extra round-trip.

The full enum lives in code at app/models/concerns/charge/failure_messages.rb — it carries the canonical list (currently ~53 entries; the set evolves as Frame's processors normalize new issuer behavior). The table above covers the most commonly encountered codes; consult the openapi spec or the Charge schema for the current complete list.

Gotchas

Symptom: you keep retrying a charge after do_not_honor and the customer is getting frustrated. Why: do_not_honor is the issuer's way of saying "we're not telling you why, but stop." Persistent retries against a do_not_honor decline can land the merchant on the issuer's velocity-limit watchlist or trigger a fraud flag. Fix: one retry is reasonable; multiple retries on the same card with the same code is not. Route the customer to an alternative payment method.

Symptom: the decline code is authentication_required but you don't have 3DS configured. Why: some issuers require 3D Secure for higher-risk transactions and will decline non-3DS attempts. Frame.js handles this automatically when you're using its Card element — without frame-js, you'd need to integrate 3DS yourself. Fix: use frame-js for card collection, or accept that some transactions will fail without 3DS configured. See 3D Secure.

Symptom: sandbox transactions return testmode_decline. Why: you're using a sandbox key against a non-test card number, or a production key against a test card. Fix: match the key environment to the card. Sandbox key + test card numbers from Testing; production key + real cards.

Reference

For charge-flow troubleshooting, see POST/v1/transfers and Accept a payment for the integration-side patterns.