How should payment UX handle pending, failed, and refunded states?
Published
Payment UX should show the payment service’s confirmed state, explain the next event, and offer only actions that are safe for that state. A customer who sees a spinner needs to know whether the request was received, whether money has moved, and whether another attempt could create a duplicate payment.
This is a design checklist for product teams, not an implementation recipe or financial advice. The proposed labels must be mapped to the actual payment methods and backend events before they ship.
What should the payment state model include?
Start with a shared state map that designers, engineers, and payment operations can inspect together. Stripe’s payment lifecycle explanation describes payments as a state machine and explains why asynchronous events matter. The design implication is straightforward: a browser interaction alone should not determine the payment’s final status.
The following is a proposed customer-facing vocabulary, not Stripe API terminology or a universal sequence. Some methods skip states, require additional states, or revisit an earlier one.
- Submitted: The system has received the request. Show a reference and explain that the outcome is not yet confirmed.
- Pending: Processing continues. Explain whether the customer needs to act and where an update will appear.
- Needs action: Name the action, such as completing an authentication step, and provide a way to resume it.
- Failed: The attempt did not complete. Explain the available next step using a confirmed reason that is appropriate to disclose.
- Paid: The product’s defined payment condition has been met. Show the amount, currency, recipient, and reference. Do not imply that every later settlement or dispute risk has disappeared.
- Refund requested: A refund request exists, but completion is not confirmed. Distinguish a request awaiting review from a refund already being processed.
- Refund completed: The payment service reports the refund outcome. Explain any remaining visibility delay only when the provider supports that statement.
What information belongs beside the status?
Give each state a short explanation, the last confirmed update, and the next permitted action. Include a durable payment reference that support can use. If the product cannot retrieve current information, say that the status is unavailable rather than converting uncertainty into failure.
Review wording against the payment method. “Payment received” and “Transfer initiated” make different promises. Timelines need an owner and evidence; do not invent a reassuring arrival estimate to fill an empty design.
Illustrative copy for a confirmed pending state: “Your payment is processing. Check this payment’s status before starting another one.” The team should adapt this only after confirming the actual recovery path and whether the existing request can still complete.
When should the customer be allowed to retry?
Ask engineering to define what happens when a customer taps twice, loses connectivity, closes the app, or returns from an external authentication screen. The interface needs a recovery path to the existing attempt, and the backend needs duplicate-prevention behavior appropriate to the integration.
Disabling a button is useful feedback, but it does not establish that protection. Document when a retry resumes the same attempt and when it starts a new one. If the first outcome is unknown, retrieve it before presenting a fresh payment action.
In a prototype test, interrupt the journey deliberately. Ask the participant what they believe happened and what they would do next. A polished confirmation screen says little about a customer who never reaches it.
What should payment operators see?
The payer needs an understandable status and next step. An operator may also need event history, matching information, exceptions, and the actions their role permits. These views should describe the same underlying payment without exposing unnecessary internal detail to customers.
Stripe’s bank transfer article explains that the payer controls a transfer’s amount and timing, which creates reconciliation problems such as overpayment and underpayment. For a design review, include a transfer that arrives with the wrong amount or cannot yet be matched to an invoice. A generic success badge does not explain what an operator should resolve.
Why can a requested refund remain pending?
Stripe documents a specific example: when the available Stripe balance cannot cover a card refund, the refund remains pending until sufficient funds are available. For other payment-method types, insufficient balance can make the refund fail. The interface must therefore use the confirmed provider state rather than treat the operator’s refund click as completion.
For interrupted requests, Stripe supports idempotency keys to recognize retries of the same operation. This is backend behavior, not protection supplied by a disabled button.
- Illustrative test: an operator requests a partial card refund while the available balance is insufficient.
- The customer sees that the refund is pending, with the amount and a support reference.
- The operator sees the reason and permitted next step without creating another refund request.
- After processing resumes, both views reflect the same confirmed event history. Do not promise an arrival date that the payment provider has not supplied.
Sources: Stripe refund behavior · Stripe idempotent requests
How should the team test refunds and recovery?
Prepare example records for a partial refund, a refund awaiting approval, a failed refund, and a customer returning before the status refreshes. These are proposed test cases, not claims about every provider’s available features. Confirm which ones the product supports.
For each case, check the visible amount, status history, notification wording, support reference, and available actions. Test customer and operator screens against the same record. The design is ready for implementation when the team can trace each message to an actual event and explain every button’s consequence.
A payments product design brief should include that state map and test set. The fintech design agency comparison can help shortlist partners; ask candidates to review an interrupted payment journey as well as the checkout screen.
