Rewriting a Checkout Payment Error
A checkout flow currently shows this error whenever a card payment fails for any reason: "Payment failed. Error code: PAY_declined." Support tickets show users are confused about what to do next and frequently retry the exact same card five or six times before giving up.
- Diagnose what's wrong with the current message using the what/why/how-to-fix structure — which parts are missing?
- The payment can fail for at least three different underlying reasons: the card was declined by the issuing bank, the card details entered don't match the card (e.g. wrong CVV), or the card has expired. Write a specific, rewritten error message for each of the three cases.
- Should all three rewritten messages be shown with the exact same voice and tone, or should tone shift between them? Justify your answer.
- What's one thing the current message does that a well-designed error message should never do, independent of the wording?
1. Diagnosing the current message
"Payment failed. Error code: PAY_declined" has a weak "what" (it names the failure but not in terms a shopper understands — "declined" by whom, for what reason?), no "why" at all beyond a raw internal error code that means nothing to a non-technical user, and critically no "how to fix it" — there's no next step, which is exactly why users are retrying the identical card repeatedly: the message gives them no information to change their behavior, so blind retry is the only thing left to try.
2. Three rewritten messages, one per cause
- Bank declined the card:
"Your bank declined this payment. This is usually due to insufficient funds, a spending limit, or a security hold — not an issue with our checkout. Try a different card, or contact your bank to authorize the charge."
- Details don't match (e.g. wrong CVV):
"The security code (CVV) doesn't match this card. Double-check the 3-digit code on the back of your card (4 digits on the front for Amex) and try again."
- Card expired:
"This card expired on {expiration date}. Try a different card, or update this one with a new expiration date if you have a renewed card."
Each names the specific cause in plain language, and each gives a concrete, different next step — "try another card" is not the right fix for a wrong CVV (retrying the same card with a corrected code is), so collapsing all three into one generic message would send users toward the wrong corrective action as often as the right one.
3. Voice and tone across the three messages
The voice should stay constant across all three — calm, plain, non-blaming (note none of the three messages imply the user did something wrong; "your bank declined this" and "the code doesn't match" describe facts, not user error). Tone should stay fairly consistent too, since all three are similar-stakes moments (checkout friction, not data loss), but there's a small justified shift: the bank-decline message is slightly more reassuring ("not an issue with our checkout") because it's the case most likely to make a user doubt the merchant's reliability, while the CVV message is more instructional and specific since it's a simple, fully user-fixable typo-class error. The shift is subtle, proportional to the stakes each message carries, not a wholesale change in personality.
4. What the current message does that a good one never should
It surfaces a raw internal error code (PAY_declined) directly to the end user. A well-designed error message translates internal state into user-facing language every time — an internal code can be logged for support/engineering to see, but showing it as the primary (or only) explanation to the shopper offloads the translation work onto the person least equipped to do it, which is precisely backward.
Share this question