Failure reasons must be understandable and actionable
Aliases: payment declined · decline copy · actionable payment error
What it is
When a rail or risk check clearly refuses this payment, the UI must say what happened and what to change: insufficient funds, expired card, issuer decline, over limit, scheme not accepted. Actionable means the next step is not empty “please retry,” but another method, another card, a lower amount, or calling the issuer. This is copy for a known failure, not an unknown state after timeout, and not whether retry would charge twice.
Why it happens
The raw signal is a rail code, meaningless to people. They need a mapping onto something they can operate: this card, this wallet, this amount. A wrong mapping yields a wrong act—insufficient funds but tap the same card again; issuer decline but edit the address. Blame framed as “your operation was incorrect” adds shame, and people leave without trying another method. Understandable also splits what the merchant can fix (another method) from what only the bank can fix (issuer risk), so people do not wait on the merchant page for nothing.
Studying it
Use real declines (NSF, expired, issuer, merchant unsupported). Compare rail-raw text, generic “payment failed,” and mapped action copy.
Independent variables: whether the object is named, whether a substitute method is offered, whether the raw code is exposed. Dependent variables: correct method/card change, pointless retry, leave, restating the reason to a third person.
Putting the reason in the lab script contaminates comprehension. Use real or simulated decline codes. Do not treat “eventually paid” as copy success—someone may have switched cards at random.
Where it stops holding
Fraud refusals cannot spell out rules; the action becomes “another method or try later” plus a support id. When someone standing nearby should not see “insufficient funds,” details can collapse, with a neutral failure plus “see reason” by default. Unknown rail codes must not be invented into a specific cause—that is guessing; unknown belongs to lookup, not a fake known failure.
Applying it
- Map the decline to object + action: card, wallet, amount, bank. The primary control points at the likeliest fix (another method, another card), not resubmitting the same intent.
- Keep the raw code as secondary for support, never as the only copy.
- If the same failure repeats, escalate the advice (another method, call the bank); do not infinite “try again.”
- Verify NSF, expired, and issuer-decline orders with docs covered: “what would you change to pay?” Failure: “tap again” or editing an unrelated field.