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.

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.

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:

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

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.