Payment states to agree on before integration

Separate orders from payment attempts

An order describes what someone intends to buy. A payment attempt describes one effort to collect its payment. A customer may cancel and try another method, so keeping these concepts separate preserves the history of each attempt.

Define order and attempt identifiers and how the provider identifier maps to an attempt. The server should verify the amount, currency and product instead of treating client-supplied values as final authority.

Separate customer-facing messages from operational detail. Customers need an appropriate next action; operators need to trace an attempt to the external response associated with it.

Represent uncertainty separately from failure

Closing a payment screen or losing a connection does not establish that processing failed. The provider may have completed the operation without the app receiving its response. Offer status reconciliation before encouraging another payment.

• Preparing or in progress: creating the request or waiting for input.
• Awaiting confirmation: the final outcome is not yet known.
• Completed, failed or canceled: a confirmed outcome determines the next action.
• Refund requested, processing, completed or failed: a separate lifecycle after payment.

This is an illustrative model. Map actual states and permitted transitions to the provider being integrated.

Do not depend on notification order or uniqueness

Review the server confirmation path separately from the return screen. A browser reaching a completion URL is not sufficient authority to finalize an order; display the result verified by the server.

Stripe’s webhook documentation describes duplicate events, ordering differences and signature verification. Check the selected provider’s contract and make repeated or late events safe to handle.

Distinguish receiving an event from finishing downstream work. If fulfillment fails after payment confirmation, records should show where to resume. Provide an operational way to reconcile stored state with the provider rather than relying only on the initial notification.

Verify failures, retries and recovery

In the provider’s test environment, exercise cancellation, interrupted connections, delayed outcomes, repeated requests, duplicate events and refund failures. Check consistency between the order, its attempts and the message shown to the user.

Refresh after a delayed confirmation and verify the final result. Replay an event and confirm fulfillment is not repeated. Also test requests with changed amounts or unrelated order identifiers.

Operations need an identifiable queue of unresolved cases and a traceable history. Preserve correlation without indiscriminately logging sensitive payment information. Completion includes a recovery procedure as well as a successful checkout screen.