Payment Gateway Integration Diagram: Authorization, 3-D Secure, Capture and Webhooks

On most architecture diagrams a payment is one arrow from the shop to "Stripe" or "Adyen". In production it is a chain of parties and two timelines: what happens while the customer waits on the checkout page, and what arrives minutes or days later by webhook. Most payment bugs live in the gap between the two.

This guide draws a card payment from the merchant engineer's point of view: the parties, the happy path, why the browser's result is not the source of truth, what happens after authorization, and a diagram that shows where money and order state change. It is vendor-neutral; Stripe and Adyen appear only as examples of how payment service providers document the details.

The parties

The happy path

1. The customer selects Pay. The frontend asks your backend to start checkout for an order.
2. The backend creates a payment at the PSP with the amount, the currency, the order ID and an idempotency key, and passes the PSP's client token to the frontend.
3. The frontend collects card details in the PSP's fields, usually iframes or an SDK, so the card number goes from the browser straight to the PSP and never touches your servers.
4. The issuer decides on 3-D Secure. EMVCo describes two flows: in the frictionless flow, the issuer approves based on a risk assessment without asking the customer anything; in the challenge flow, the customer confirms, for example with a one-time code or a banking app. In some regions this is how strong customer authentication is met.
5. The PSP sends the authorization through the acquirer and the card network to the issuer, which approves and holds the funds.
6. The frontend shows the result. "Thank you" is fine to display, but it is not the moment to ship.
7. The PSP sends a webhook saying the payment was authorized. Your backend verifies it and updates the order.
8. The backend captures the payment when the order ships, or right away for digital goods.
9. The PSP pays out, in batches and minus fees, and a reconciliation job matches payouts to orders.

The card fields matter for compliance. When an e-commerce site only embeds a PSP's payment form and stores, processes and transmits no card data itself, it may qualify for PCI DSS SAQ A instead of the much longer SAQ A-EP. Under PCI DSS v4.0.1 that also requires protecting the page from malicious scripts, as the PCI Security Standards Council explains. Confirm the right questionnaire with your acquirer.

Why the browser is not the source of truth

The customer can close the tab during 3-D Secure, lose the connection after the issuer approved, or hit refresh at the wrong moment. If your order state depends on the browser reporting back, some paid orders will stay unpaid and some failed ones will look paid. The PSP's webhooks, or its API, are the source of truth. Treat them like any other message stream:

• Verify the signature. PSPs sign webhook requests, for example Stripe in a Stripe-Signature header and Adyen with HMAC signatures. Reject anything that does not verify.
• Answer fast, process later. Stripe's webhook guide asks for a 2xx response before any complex logic. Put the verified event on a queue and return.
• Expect duplicates. Endpoints can receive the same event more than once. Record processed event IDs and skip repeats.
• Do not rely on order. Stripe states that it does not guarantee delivery in the order events were generated. When an event arrives that does not fit the current state, fetch the payment from the PSP's API.
• Expect retries. Stripe retries failed deliveries for up to three days in live mode, with exponential backoff, so a slow endpoint gets the same event again later.

The same discipline applies in the other direction. Send an idempotency key with every request that creates or changes a payment, and reuse it when you retry after a timeout, so a retry cannot charge twice. Keys do not live forever: Stripe may remove them after 24 hours, and Adyen keeps them for 7 to 14 days.

After authorization: capture, refunds, chargebacks and payouts

• Authorization holds; capture moves money. An authorization expires if you do not capture it. For online card payments the window is typically about a week, and Stripe lists it per card brand and per who initiated the payment. Capture before it runs out, or the hold is released.
• A capture can still fail. Adyen documents rare cases where the card scheme rejects a capture after the PSP accepted it, so your order states need a path for that.
• Refunds are new operations on a captured payment. They complete asynchronously and arrive as webhooks too.
• Chargebacks come from the issuer, sometimes weeks later, when a cardholder disputes a payment. Some networks start with an inquiry first; answer it, or it can turn into a chargeback that is hard to win.
• Payouts need reconciliation. Match each payout to the payments, refunds, fees and chargebacks it settles, using the PSP's payout or settlement reports.

The diagram

How to read it:

• Solid edges are the checkout itself: pay (1), start checkout (2), create the payment (3), send card details to the PSP from its fields (4), and 3-D Secure and authorization between the PSP and the card network (5).
• Dashed edges happen later: the webhook (6), the verified event on a queue (7), and the payments API updating the order (8). The nightly reconciliation job reads the PSP's payout reports and matches them to orders.
• The frame marks the merchant's systems. No raw card data enters it; the card number goes from the PSP's fields straight to the PSP.

How to draw a payment flow

• Number the steps. Payments are sequences; numbers make the order readable without a separate sequence diagram.
• Separate synchronous from asynchronous. Solid for the checkout request, dashed for webhooks, queues and batch jobs.
• Mark the card data boundary. Show which components can see card numbers. With hosted fields, none of yours should.
• Show where order state changes. One component should own it, fed by verified events, not by the browser.
• Name the money operations. Authorize, capture, refund and payout are different events with different timing; label them.
• Draw the failure cases that matter: a timeout on create (retry with the same idempotency key), a duplicate webhook (deduplicate), an abandoned 3-D Secure challenge (expire the order), an expired authorization (re-authorize or cancel).

For a sequence view of the same flow, see the payment flow diagram use case. For the event side, see the event-driven architecture diagram guide, and for the security review, data flow diagrams for threat modeling.

Build it in Archboard

1. Sign in with Google or GitHub and create a diagram.
2. Add a C4 Model Person for the customer and two C4 Model External System nodes for the payment service provider and for the acquirer, card network and issuer.
3. Add a Core Frame for the merchant systems and put four C4 Model Container nodes in it: the checkout web app, the payments API, the webhook handler and the reconciliation job.
4. Add a Data pack Postgres for orders and payments and a Data pack Queue for payment events inside the frame.
5. Number the edges in order, make the webhook, queue and reconciliation edges dashed, and add a Core Markdown block that explains the line styles.

The example uses 11 diagram nodes, within the Free plan.

FAQ

What is the difference between a payment gateway and a payment processor? The gateway is the interface your systems talk to: API, card fields, webhooks. The processor moves the transaction through the card networks. Many PSPs provide both, together with an acquiring relationship.

Can I mark an order as paid when the browser says the payment succeeded? Show the customer a confirmation, but change the order state only from a verified webhook or a check against the PSP's API.

Why authorize first and capture later? To charge only for what ships. A hold guarantees the funds; capture moves them when you fulfill. Watch the authorization expiry.

Do I need to handle webhooks arriving out of order? Yes. Make the handler idempotent, keep the order as a state machine that rejects impossible transitions, and fetch the current payment from the PSP when in doubt.

Does using hosted fields make me PCI compliant? It reduces scope; it does not remove it. You still complete a self-assessment questionnaire and protect the checkout page. Ask your acquirer which one applies.

Start free — one seat, no credit card.