Decline reasons

The closed decline_reason vocabulary and safe copy to show customers.

decline_reason is a closed, finite vocabulary — every value it can ever carry is listed on this page. Match on it exhaustively (with a fallback for redacted) instead of pattern-matching or substring-checking the string: the set only grows by an explicit change to this catalog, never silently.

Where it appears

decline_reason rides two places, both only ever set on a decline:

• Transaction.decline_reason — returned by Get a transaction and List transactions.
• the authorization.decided webhook event payload's decline_reason.

It's absent on an approval. On a stood-in decline (stip: true — the authorizer couldn't reach a normal decision in time and fail-closed rather than risk an unauthorized approval) it's one of the stand-in tokens below.

Because the set is closed at the wire, not just documented, a decision that carries a reason this catalog hasn't caught up with does not reach you labelled with something unlisted — it's held back for review instead. You will only ever see one of the tokens below.

One field named decline_reason is not part of this vocabulary: the one on a sandbox simulation record. It carries raw network wire codes instead — see Sandbox wire vocabulary before you assert on it.

The same two surfaces also carry a decision's evidence trace, and there the split is sharper than a difference in location:

Decision evidence appears under two names by surface convention: the REST transaction carries trace (camelCase entries, durationMs); the authorization.decided webhook event carries decision_trace (snake_case, duration_ms). They are the same provenance — pin your parser to the surface you consume, not the other one's field name.

Card state

Facts about the card itself.

card_expiry_mismatch, card_expiry_unknown and card_expired deliberately share one token family and answer the same way on the network — telling them apart on the wire would let a stolen card number be probed for its real expiry a few dozen guesses at a time. Don't build UI that implies they're distinguishable; the copy above works for all three.

Controls

A programme-level rule matched, or a required allow-list rule didn't.

control_currency_mismatch is retired but not removed. No new decline will carry it: a spend limit is now a plain number denominated by the card, so a limit and a card can no longer disagree about currency.

It stays listed because this vocabulary only ever grows — a value that disappeared would break any consumer matching it exhaustively, and decisions already recorded with it keep their meaning. Leave your existing branch in place: it is no longer reached for new declines, but a decision recorded before this change still carries it, so anything replaying or reporting over history will keep meeting it.

Velocity

The card hit a rolling window limit.

Fraud and risk

A risk verdict about this transaction rather than a rule it broke. Both tokens are deliberately unspecific about what was noticed — a decline that named the signal it tripped would tell someone testing cards exactly what to change.

While that pause is in force, every transaction on the card gets cvv2_attempts_exceeded — including one presenting the correct security code. That is deliberate: an attempt that broke through the pause would tell a guesser they had found the right code.

These two are produced by the platform's risk engine, which scores the authorizations we decide once the card, control and velocity checks have passed. On a programme that decides its own authorizations (Gateway mode), it is skipped before it reads anything — the decision is yours, so scoring it would spend your deadline on a verdict nobody would consult — and neither token can reach you. They were listed here before the first decision could carry one — for the reason this page's opening paragraph gives: the vocabulary is closed at the wire, so a consumer matching it exhaustively is better served by a token it has an arm for and has not yet seen than by one that shows up undocumented.

Funding

The ledger side of the decision — whether the money is there and postable.

cross_currency is the one token listed here that can also be answered earlier, straight from the card record and before any ledger call. The meaning, the network response code and the copy are identical either way, so nothing consuming it needs to tell the two apart.

Engine

Not a fact about the card, the cardholder, the funds, or a stand-in — the decision pipeline itself misbehaved.

Stand-in (stip_*)

When the authorizer can't reach a normal decision before its deadline — a dependency is down, the request budget ran out, or its own configuration isn't warm — it fails closed with stip: true rather than risk an unauthorized approval. decline_reason on a stand-in decline is always prefixed stip_, and every value below is one this build emits today:

Almost every stand-in reason answers the same for a consumer — it's a transient, our-side failure, not a fact about the card, the cardholder, or the funds:

"We couldn't process this purchase right now. Please try again in a moment."

One exception, and it matters if you retry automatically. stip_idempotency_key_malformed is not transient: it means the request could not be tied to an account scope at all, so an identical retry fails identically, every time. Treat it as you would a 400 — the cardholder message above is still the right thing to show, but retrying the same request will not help, and a retry loop on it will never terminate. If you see it, the request is malformed on our side or yours; tell us.

stip_fraud_unavailable is not a risk verdict, and the distinction is worth holding on to. It means the programme's risk settings could not be read, so the transaction was never scored at all — nobody judged this cardholder. It is transient and the standard message above is the right one; in particular, do not show the fraud copy from the Risk section, which would tell a cardholder something about themselves that we did not conclude.

redacted

A reason existed on the decision, but its detail wasn't safe to publish verbatim — or, on a build ahead of this catalog, wasn't in this vocabulary at all. Treat it exactly like any other decline with no more specific information available:

"We couldn't complete this purchase. Please try again or contact support."

Building consumer copy

Match on decline_reason exhaustively, with redacted — and the case where decline_reason is absent on a declined transaction — folding into the same generic fallback. That combination is what the closed vocabulary buys you over substring-matching the field: every branch you write is a real, listed token, and anything the switch doesn't recognise is provably out of date rather than a token you can't reproduce.

const COPY: Partial<Record<string, string>> = {
  insufficient_funds: "Insufficient funds. Add funds to your account and try again.",
  card_expired: "This card has expired. Order a replacement in the app.",
  amount_over_cap: "This purchase is over your card's spending limit.",
  // ...the rest of the table above.
};

const FALLBACK = "We couldn't complete this purchase. Please try again or contact support.";

function copyForDecline(declineReason: string | undefined): string {
  if (declineReason === undefined) return FALLBACK;
  return COPY[declineReason] ?? FALLBACK;
}

Don't infer meaning from a decline reason's shape (a _ count, a prefix other than stip_, or its length) — new tokens are added to categories over time, and a shape-based guess breaks silently the day that happens. Read the full event catalog for how decline_reason sits inside the rest of the authorization.decided payload.

Sandbox wire vocabulary

There are two decline surfaces, and they speak different languages.

Transactions and webhooks — everything above — publish the closed vocabulary: a token that names the decision (mcc_denied, entry_mode_denied, card_lost). It is a contract. It is finite, it is reviewed, and a reason outside it never reaches you.

Simulation records — GET /v1/simulated-spends/{id} — publish something else entirely: the raw network wire code, translated only as far as its standard ISO 8583 meaning. The sandbox simulator sits on the far side of the wire from the authorization engine and deliberately never learns why a decision was made; all it can see is the DE39 response code that came back, so all it reports is what that code means (do_not_honor, lost_card, stolen_card, insufficient_funds, not_permitted_to_cardholder, and so on — an unrecognised code is passed through as declined_<code>). That set is open-ended by design: it tracks the network, not our catalog.

Two consequences worth internalising before you write an assertion against a simulation record:

The mapping is many-to-one. A single wire code carries several distinct published reasons. mcc_denied and entry_mode_denied both leave the engine as DE39 57, so the simulation record for either one reads not_permitted_to_cardholder. You cannot recover which control actually fired from the record's decline_reason — read the transaction or the authorization.decided event for that.

The spellings near-miss. The wire token for a lost card is lost_card. The published token is card_lost. Same two words, opposite order, different surfaces — and a switch written against one vocabulary will fall straight through to its default on the other while looking perfectly correct in review. This is the single most likely way to get this wrong.

So: to assert on the decision in an integration test or a verification runbook, read the transaction or the authorization.decided event and match against the vocabulary on this page. Read a simulation record's decline_reason only for what it is — evidence of what came back over the simulated wire — and never match it against the tokens above.