Skip to content
sysgeeks

Design a Payment System, stage 1 of 13: model

What the provider's behaviour implies

The provider's documentation is a list of facts. A design starts by turning each one into a consequence. Before you write any code, decide which of these statements follow from the constraints.

System so far· 4 parts
12CLIENTBuyer's browserSERVICECheckout APIDATABASEPostgresEXTERNALPayment provider

Select a component to see what it is responsible for and which state it owns.

  1. 1Buyer's browser → Payment provider: Card entry and 3-D Secure in hosted fields
  2. 2Buyer's browser → Checkout API: Pay (Idempotency-Key header); poll status

What you need to know

0 of 2 checks done

  1. A timeout ends your waiting, not the other side's work. When a request to the provider times out, three things are possible: the request never arrived, it arrived and failed, or it arrived and succeeded and only the response was lost.

    From your side these look identical. A design that treats a timeout as "failed" will one day mark a successful charge as failed and let the buyer pay again.

  2. An idempotency key is a value you send with a request so the receiver can recognise a repeat. This provider stores each key for 24 hours: a second request with the same key returns the first result instead of charging again. See Idempotency.

    A webhook is the provider calling your server when something changes. These are delivered at least once (possibly twice), in no guaranteed order, and retried for three days if your endpoint fails.

  3. Check

    A request with idempotency key K succeeds. 30 hours later, a buggy client retries with the same key K. What does the provider do?