Payment System Design

A payment flow is the standard example of a workflow you cannot make atomic: your database and the payment provider are two systems with no shared transaction, and money has already moved by the time you find out whether your own write succeeded. Six building blocks handle that, and they are not independent options — each one closes a gap the others leave open. An idempotency key, sent by you with the charge request, lets the provider recognise a repeated request as the same request and return the original result instead of charging again, which is what makes a retry after a timeout safe. Immutable transaction records mean you append what happened rather than updating a row in place, so a refund is a new row and the original charge is still readable — an audit trail you can reconcile against, rather than a current value you have to trust. Explicit payment states (`requires_payment_method`, `processing`, `succeeded`, `failed`) replace a boolean `paid` flag, so the very common in-between state has a name and the code has somewhere to put it. Webhook processing is how you learn the outcome of anything asynchronous, because a payment can complete minutes after the customer closed the tab. Reconciliation is a scheduled job that compares your records against the provider's and reports the differences, on the assumption that some will exist. And retry-safe operations means every step in the flow can run twice without a second effect — which is what the previous five blocks together are for.

POST /v1/payment_intents HTTP/1.1
Host: api.stripe.com
Idempotency-Key: order_8814_attempt_1
Content-Type: application/x-www-form-urlencoded

amount=4200&currency=usd&customer=cus_...

# Same key again -> the original PaymentIntent is
# returned. No second charge is created.

After a customer pays on a provider's hosted page, their browser is redirected back to a success URL on your site. That redirect is a navigation event in a browser you do not control, and it is not a statement from the provider that money moved. Three things are wrong with treating it as one. It can be forged: the URL is visible in the address bar, and anyone can type it, bookmark it or share it, so a request to `/checkout/success?order=8814` proves only that someone requested that path. It can be missed: the customer closes the tab, loses signal, or the payment method completes asynchronously minutes later, so a genuinely successful payment produces no redirect at all. And it can arrive before the payment is final: some methods redirect while the charge is still pending, so the redirect is truthful about "the customer finished their part" and silent about "the money settled". The correct design uses the redirect for exactly one thing — deciding what to show the customer next — and takes the actual payment outcome from a server-side source: a webhook from the provider, or a server-to-server lookup of the payment by its id. Fulfilment, entitlement and receipts hang off that source, never off the redirect.

# The success route decides what to SHOW, nothing else
@app.get("/checkout/success")
def success(payment_intent_id: str):
    # server-to-server, not the query string
    intent = provider.retrieve(payment_intent_id)
    if intent.status == "succeeded":
        return render("thanks.html")
    return render("confirming.html")   # webhook will
                                       # settle it

A single `status` column on an order tries to hold two different lifecycles at once, and they do not line up. The payment lifecycle belongs to the provider and moves through states like requires-payment-method, processing, succeeded, failed, refunded, disputed. The fulfilment lifecycle belongs to you and moves through pending, allocated, packed, shipped, delivered, returned, cancelled. These progress independently: a payment can succeed while fulfilment has not started, fulfilment can be underway while a dispute is opened, and a refund can happen long after delivery. Squashing both into one enum forces you to invent hybrid values — `paid_but_not_shipped`, `shipped_refund_pending` — and the count of those values grows as the product of the two lifecycles, not their sum. Two state machines with an explicit link between them keeps each one small and independently correct, lets each move at its own speed, and makes the interesting questions answerable with a query: which orders are paid and unfulfilled, which are fulfilled and unpaid. The link is a rule you write down — typically "fulfilment starts when payment reaches succeeded" — rather than a shared column that pretends the two lifecycles are one.

-- two columns, two machines, one link rule
CREATE TABLE orders (
  id            uuid PRIMARY KEY,
  payment_state text NOT NULL,   -- provider's machine
  fulfil_state  text NOT NULL,   -- yours
  CHECK (fulfil_state = 'pending'
         OR payment_state = 'succeeded')
);

-- the question a single enum cannot answer cleanly
SELECT id FROM orders
 WHERE payment_state = 'disputed'
   AND fulfil_state IN ('shipped', 'delivered');