Payment collection

Problem Context

• The user needs to pay a known fee, invoice, balance, tax, application charge, renewal, subscription, donation, deposit, or service request.
• The service may collect through card, wallet, bank redirect, payment link, hosted page, embedded payment element, saved method, manual reconciliation, or pay-later route.
• The payment lifecycle can include not started, method selection, requires details, requires action, processing, authorized, requires capture, succeeded, failed, canceled, expired, refunded, or disputed states.
• Users may leave for bank authentication or a hosted provider and then return by redirect, browser Back, webhook update, email link, or support route.
• Payment status affects whether the service can continue, issue a receipt, reserve inventory, submit an application, unlock access, or start fulfillment.

Selection Rules

• Choose payment collection when the main task is taking or reconciling money for a known amount and reference.
• Use checkout when the payment is embedded inside cart, delivery, tax, discount, inventory, and order finalization.
• Use payment-card entry when the primary surface is card number, expiry, CVC, billing postal code, tokenization, and card-specific field recovery.
• Use bank details when collecting account identifiers for payout, direct debit, refund, payroll, or account-to-account transfer rather than collecting money now.
• Use retry when the same failed request is being attempted again; payment collection decides whether retry uses the same attempt, same reference, new method, or support path.
• Use confirmation page only after the payment succeeds or after the service accepts a pending payment state with clear next steps.
• Show amount, currency, reference, description, payer or account context, and what the payment unlocks before the user leaves for a provider or submits details.
• State who processes the payment, what methods are accepted, whether fees apply, and what happens after bank authentication or redirect.
• Use hosted fields, embedded payment elements, hosted pages, or redirects for sensitive payment credentials when the product should not own credential capture.
• Preserve the payment reference, amount, and service context across redirect, browser Back, failure, cancel, timeout, and support handoff.
• Disable or guard duplicate pay actions while authorization, capture, order creation, or status verification is in flight.
• Distinguish not attempted, requires action, processing, failed, canceled, succeeded, refunded, and pending reconciliation states in user-facing copy.

Required States

• Payment request state with amount, currency, reference, description, payer context, accepted methods, and secure provider handoff.
• Method selection state for card, wallet, bank redirect, saved method, payment link, or alternate route.
• Sensitive details state delegated to hosted or compliant payment UI.
• Provider redirect or authentication state with clear return expectations.
• Processing or pending status state that prevents duplicate payment while status is uncertain.
• Requires action state such as bank authentication or mandate acceptance.
• Failed or declined state with reason category, preserved context, and retry or alternate-method route.
• Canceled or abandoned state with safe resume or start-new-payment route.
• Expired payment session state with a new attempt route tied to the same service reference where appropriate.
• Succeeded state with receipt, payment reference, amount paid, date, and next step.
• Refunded, partially refunded, or reversed state when relevant after payment.
• Status lookup or reconciliation state for asynchronous provider updates and support.

Interaction Contract

• Every payment attempt is tied to a stable service reference, amount, currency, and payer context that remains visible before and after provider handoff.
• The final pay action names the amount or consequence and becomes busy or disabled while the payment attempt is being created or confirmed.
• Redirect returns restore the same payment context and immediately show the latest known provider status or a status-checking state.
• Failure, cancel, timeout, and retry keep non-sensitive service data while clearing or delegating sensitive payment credentials according to provider rules.
• Retry uses idempotency or a clearly new attempt policy so users cannot accidentally create duplicate charges.
• The interface never claims payment succeeded until the provider or trusted backend status supports that state.
• Successful payment removes editable payment controls and hands off to receipt, confirmation, or the next service step.

Implementation Checklist

• Define payment owner, amount source, reference format, idempotency strategy, provider surface, accepted methods, status model, retry rules, refund rules, and reconciliation source before designing the UI.
• Design request, method selection, provider handoff, authentication, processing, failed, canceled, expired, succeeded, refunded, and status-lookup states.
• Bind amount, currency, reference, description, and payer context to canonical backend records rather than browser-only state.
• Use hosted provider pages, payment elements, or compliant credential capture for sensitive details and avoid storing payment secrets in application state.
• Handle webhooks or backend status polling for asynchronous success, failure, processing, refund, and reconciliation events.
• Add idempotency keys, duplicate-submit guards, and clear busy states for payment creation, confirmation, capture, and retry.
• Preserve payment context across redirect, browser Back, refresh, session timeout, provider cancel, decline, and support handoff.
• Redact payment credentials, provider tokens, full card data, bank details, failure payloads, and personal data from logs, analytics, screenshots, replay tools, and support transcripts.
• Test double submit, redirect return, bank authentication, wallet cancel, decline, processing delay, status polling, provider outage, expired session, refund display, mobile viewport, screen readers, and high zoom.

Common Generated-UI Mistakes

• Showing a Pay button without amount, currency, or reference.
• Letting users submit the same payment twice while the first attempt is processing.
• Clearing the service context after a decline, cancel, or provider redirect.
• Collapsing declined, canceled, expired, processing, and provider-unavailable states into one payment failed message.
• Claiming success before backend or provider status confirms payment.
• Collecting raw card or bank credentials directly when a hosted or compliant provider surface should own them.
• Generating a new reference on every retry without explaining whether a duplicate charge is possible.
• Sending users to a receipt page without payment reference, amount paid, timestamp, and support route.

Critique Questions

• What amount, currency, reference, and service outcome is this payment tied to?
• Which surface owns sensitive payment credentials, and what must never enter product logs or state?
• What exact states can the provider return, and how are they shown to the user?
• Can users safely return from authentication, cancel, refresh, browser Back, or support without losing payment context?
• How does retry avoid duplicate charges or duplicate service submissions?
• When is it safe to show receipt or confirmation, and what evidence proves that status?