How to Diagram a Payment Flow
Payment flows fail in expensive ways - double charges, lost captures, missed webhooks. Diagramming authorization, capture, and the async callbacks is how you get the edge cases right before real money moves.
Payments look like a single "charge the card" step and are actually a multi-stage, partly asynchronous dance between your application, a payment provider, and the card networks behind it. Money is authorized, then captured, sometimes much later; results arrive both synchronously in the API response and asynchronously via webhooks; and every step can fail in ways that, handled wrong, lead to double charges or orders shipped without payment. Because the stakes are literally money, the payment flow is one of the highest-value things to diagram before you build it.
This guide shows how to diagram a payment flow with a sequence diagram that captures authorization, capture, webhook callbacks, and the idempotency that keeps retries safe. Build it in Atlas Diagram Studio at /diagrams using the sequence tooling at /diagram-tools/sequence-diagram, and draft it fast with the AI diagram generator at /diagram-tools/ai-diagram-generator. The worked example is a card payment for an online order, the flow most teams need to get exactly right.
Why a sequence diagram fits payments
A payment is an ordered exchange of messages between several parties over time, which is the textbook case for a sequence diagram. The participants are the customer's browser, your server, the payment provider, and - represented through the provider - the card network and issuing bank. The vertical lifelines hold these parties and the horizontal arrows show each request and response in order, read top to bottom, which is exactly how you reason about "authorize first, then capture, then reconcile the webhook."
The sequence format is especially valuable for payments because the timing is subtle. Some results come back immediately in the response to your API call; others arrive seconds or minutes later as a webhook, out of band from the original request. A sequence diagram can show both the synchronous response and the later asynchronous callback as separate arrows, making the two-channel nature of payment results explicit. For the decision logic inside a step - approved, declined, requires further authentication - a flowchart from /diagram-tools/flowchart-maker complements the sequence diagram.
Authorization and capture
The two-step heart of card payments is authorization then capture, and diagramming them separately clarifies a design most people blur together. Authorization asks the issuing bank to reserve the funds and confirm the card is valid, without moving money. Your diagram shows the browser collecting card details, your server requesting an authorization from the provider, and the provider returning an approved or declined result. An approval places a hold on the customer's funds but does not yet charge them.
Capture is the later step that actually moves the money, and separating it from authorization is what lets you, for example, authorize when an order is placed but capture only when it ships. The diagram should show capture as a distinct request, potentially much later, referencing the earlier authorization. This split raises real design questions the diagram forces you to answer: how long is an authorization valid before it expires, what happens if you capture less than you authorized, and how do you void an authorization you decide not to capture. Each becomes an explicit arrow or branch.
The elements every payment diagram needs
A payment flow diagram has to capture the details that separate a robust integration from a leaky one. Include these.
- Authorization request and response, showing approved, declined, and requires-authentication outcomes as distinct paths.
- Capture as a separate step, with its own success and failure handling and its timing relative to authorization.
- Idempotency keys on every charge request, so a retried authorization or capture never results in a double charge.
- Webhook callbacks for asynchronous results - payment succeeded, payment failed, dispute opened - arriving out of band from the API response.
- Webhook verification: how you confirm a webhook genuinely came from the provider before acting on it.
- Failure and decline paths: what the customer sees and what your order state becomes on each kind of failure.
- Refunds and voids, showing how money is returned and how an uncaptured authorization is released.
- Reconciliation: how you reconcile your records against the provider so no payment is silently lost or duplicated.
Webhooks, idempotency, and failure
The parts of a payment flow that bite hardest are the asynchronous ones, and the diagram must make them explicit. Webhooks deliver results your API call could not wait for - a payment that settles later, a dispute opened days after. Show the webhook as an inbound arrow from the provider to your server, and show two critical steps on it: verifying the webhook's signature so you only trust genuine callbacks, and handling it idempotently because providers retry webhooks and you will receive the same event more than once. A webhook processed twice must not ship an order twice.
Idempotency is the thread that runs through the whole flow. Networks fail mid-request, so your client will retry an authorization or capture without knowing whether the first attempt succeeded. Sending an idempotency key with each charge lets the provider recognize the retry and return the original result instead of charging again - the single most important safeguard against double charges, and one the diagram should show on every money-moving arrow. Draw the declines, the expired authorizations, and the reconciliation path too. Build the flow in Atlas Diagram Studio at /diagrams and review it carefully, since these are the paths real money leaks through. The guide on how to diagram a REST API covers the request and response mechanics, and the guide on how to diagram an event-driven system covers webhook-style async delivery in general.