Rule

Payment failure states must provide an immediate, low-friction path to resolution.

Why

Confusing failure messages cause cart abandonment and avoidable support contacts.

Must

• Preserve cart or order contents across a failed payment attempt.
• Show a human-readable reason where the provider allows it.
• Provide a retry button that returns to the payment step, not the cart.
• Offer alternative payment methods on failure.
• Never log sensitive card data in error messages.

Should

• Proactively suggest common fixes for decline reason codes.
• Allow guest checkout without account creation after failure.

Anti-patterns

• Sending the user back to the product page on failure.
• Generic "payment could not be processed" with no next step.
• Logging raw provider error codes visible to end users.

Test Cases

• Declined card surfaces blame-free message and retry CTA.
• Insufficient funds suggested fix is to try a different card.

Telemetry

• payment_failed_reason_code
• payment_retry_attempted
• alternative_payment_method_selected