Skip to content

DevelopmentUpdated 2 min read

Payments and orders: design distinct, reliable states

A buyer returns from the payment provider and sees a thank-you message. Is that enough to dispatch the item? The return address alone does not confirm payment. A connection can fail, a response can be delayed or the buyer can close the page.

Treat order receipt, a payment attempt and confirmed payment as separate states. Fulfilment is another stage. Combining everything under “Completed” makes mistakes easier for both staff and customers.

Give each state a defined meaning

An order may still require payment, await confirmation or be ready for processing. One failed attempt does not establish the outcome of a later attempt. A refund and an order cancellation are different events too.

The WooCommerce REST API v1 order model distinguishes pending payment, processing, completion and other states. Map the provider’s documented behaviour to the store’s model deliberately; matching a label is insufficient.

A staff member compares an order on a laptop with a payment record
Compare order and payment records when an outcome needs reconciliation.

Verify the financial outcome on the server

Check the confirmation source, order identity, amount and currency against the expected record. Verify message authenticity using the provider’s documented mechanism. A success flag supplied by the browser should not authorise a financial decision.

A response may be repeated, or two requests may arrive concurrently. Processing protections should prevent duplicate stock changes or fulfilment. Keep a clear record of the action and later changes without storing secrets in diagnostic output.

A return page does not prove payment
Separate financial confirmation from fulfilment. An illustrative planning example.

Test interruptions as well as success

  • Payment succeeds but the buyer never opens the return page.
  • A provider notification arrives late or twice.
  • The buyer cancels an attempt and tries again.
  • The amount or currency differs from the expected record.
  • Sending email fails after payment has already been confirmed.

Compare provider and store records in the test environment. Assign responsibility and a reconciliation process for uncertain outcomes. An online-store integration is useful when each payment and order has a verifiable state and an interruption has a recovery route.

More articles