Payments

01Who is involved and how money moves

Picture four parties. The customer pays. The merchant (your shop) sells. The acquirer is the merchant's bank, usually reached through a payment gateway or provider (Stripe, Adyen, a local bank's virtual POS). The issuer is the customer's bank, which approves or declines. Card networks such as Visa and Mastercard carry messages between them. A card payment has two steps: authorisation (the issuer reserves the money) and capture (the money is actually taken). Many shops capture immediately; restaurants or stores with stock uncertainty may authorise first and capture when the order is confirmed. Settlement — the money arriving in your account — happens later, often a day or more, minus fees.

• Authorisation: "can this card pay 50.00?" — funds are held.
• Capture: "take the 50.00 now" — can be full or partial.
• Void: cancel an authorisation before capture; refund: return money after capture.

02Integration styles: redirect, hosted fields and SDKs

There are three common ways to collect card details. A redirect (hosted payment page) sends the customer to the gateway's page and back to your return URL — simplest and the smallest compliance scope, common with bank gateways. Hosted fields or embedded components (Stripe Payment Element, Adyen Drop-in) render card inputs inside iframes on your page, so it looks native while card data still goes straight to the provider. Mobile SDKs do the same in apps, and wallet apps can be opened through deep links or native modules. Whatever the style, the flow is the same: your server creates a payment session for an order with the amount and currency, the customer completes it with the provider, and your server learns the result from the provider — never from the browser alone.

1// Server: create a payment session for an existing order (Stripe example)
2import Stripe from "stripe";
3const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
4 
5export async function startPayment(order: { id: string; total: number; currency: string }) {
6  const intent = await stripe.paymentIntents.create(
7    {
8      amount: order.total, // integer minor units
9      currency: order.currency.toLowerCase(),
10      metadata: { orderId: order.id },
11      automatic_payment_methods: { enabled: true },
12    },
13    { idempotencyKey: `order-${order.id}-attempt-1` },
14  );
15  return intent.client_secret; // the client confirms with this; no card data touches us
16}

033-D Secure and strong customer authentication

3-D Secure (3DS) is the extra step where the issuer asks the customer to confirm a payment, usually in the banking app or with an SMS code. The current version, EMV 3DS (often called 3DS2), sends rich device and transaction data so many payments pass "frictionlessly" without a challenge, and only risky ones get one. In Europe, strong customer authentication (SCA) under PSD2 makes this mandatory for most online card payments; elsewhere it is optional but reduces fraud and usually shifts chargeback liability for fraud to the issuer. For you, 3DS means the payment is not instant: it may pause for a challenge, then continue. Your flow must handle a status like "requires action" and a customer who closes the tab halfway through.

04Webhooks, callbacks and idempotency

The browser redirect back to your site is not proof of payment: users close tabs, networks drop, and anyone can type a return URL. The source of truth is a server-to-server message — a webhook (the provider calls your endpoint) or a status query you make to the provider. Verify every webhook's signature, look up the payment by your own ID, and update the order inside a transaction. Providers retry webhooks, so the same event may arrive several times or out of order: store processed event IDs and make the handler idempotent, meaning running it twice has the same effect as running it once. Use idempotency keys on your own outgoing calls too, so a retried "create payment" or "refund" never charges or refunds twice.

1// Webhook handler: verify, deduplicate, apply once
2app.post("/webhooks/payments", express.raw({ type: "application/json" }), async (req, res) => {
3  const event = stripe.webhooks.constructEvent(
4    req.body, req.header("stripe-signature")!, process.env.STRIPE_WEBHOOK_SECRET!,
5  );
6  await db.transaction(async (tx) => {
7    const seen = await tx.processedEvents.insertIgnore({ id: event.id }); // unique key
8    if (!seen.inserted) return; // duplicate delivery: already handled
9    if (event.type === "payment_intent.succeeded") {
10      const orderId = event.data.object.metadata.orderId;
11      await tx.orders.markPaidIfPending(orderId); // state machine guards the move
12    }
13  });
14  res.sendStatus(200); // answer fast; heavy work goes to a queue
15});

05Payment states, "outcome unknown" and reconciliation

Keep a payments table separate from orders: one order can have several attempts. Give each attempt explicit states, such as created, pending, requires action, authorised, captured, failed, cancelled, refunded and partially refunded. Add one more that beginners forget: outcome unknown. It covers timeouts and crashes where you sent a request but never got an answer — the money may or may not have moved. Never guess. Mark it unknown, do not retry blindly with a new charge, and let a reconciliation job ask the provider for the real status. Reconciliation runs on a schedule: it finds payments stuck in pending or unknown, queries the gateway, fixes local state, and compares daily settlement reports with your ledger so every cent is accounted for.

• Retry a timed-out call only with the same idempotency key, or query status first.
• Alert on payments stuck in a non-final state for longer than expected.
• Store raw provider responses for disputes and debugging, without card data.

06Refunds, saved cards, wallets and PCI scope

Refunds go through the same discipline: create a refund record, call the provider with an idempotency key, and confirm the final status from a webhook or query, since bank refunds can take days. Support partial and per-item refunds, and never refund more than was captured. Saved cards work through tokenisation: the provider stores the card and gives you a token or customer ID you can charge later, so you keep only the brand, last four digits and expiry for display. Apple Pay and Google Pay are wallets that hand the provider an encrypted, device-specific token; they need domain verification on the web and merchant setup, but give fast, biometric checkout. PCI DSS is the card industry's security standard. If card data only ever touches the provider's pages or iframes, you qualify for the shortest self-assessment (SAQ A), though under PCI DSS 4.0.1 you must still protect the pages that load payment scripts.

07A ledger: double-entry thinking for money movements

A payments table tells you the state of each attempt; a ledger tells you where every cent went. In double-entry bookkeeping each movement is recorded twice, as a debit on one account and a credit on another, so the totals always balance. For a shop the accounts are simple: customer receivable, provider balance, fees, refunds and revenue. A captured payment of 50.00 with a 1.50 fee becomes entries that move 50.00 from the customer to the provider balance and 1.50 from the provider balance to fees. Refunds and chargebacks are new entries, never edits. When the daily settlement arrives, the provider balance should drop by exactly the payout amount. Any difference is a reconciliation finding with a precise date and reference, not a mystery in the accountant's spreadsheet.

1CREATE TABLE ledger_entries (
2  id          BIGSERIAL PRIMARY KEY,
3  journal_id  UUID NOT NULL,          -- groups the entries of one movement
4  account     TEXT NOT NULL,          -- customer, provider_balance, fees, refunds
5  amount      BIGINT NOT NULL,        -- positive = debit, negative = credit
6  currency    CHAR(3) NOT NULL,
7  payment_id  BIGINT,
8  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
9);
10 
11-- Every journal must balance to zero
12SELECT journal_id FROM ledger_entries
13GROUP BY journal_id, currency HAVING SUM(amount) <> 0;

08Webhook delivery semantics in practice

Providers deliver webhooks at least once, not exactly once, and not in order. Stripe, for example, retries failed deliveries in live mode for up to three days with exponential backoff, and states that event order is not guaranteed. Design for that. Read the raw request body, because signature verification fails if a framework parses and re-serialises it. Reject events whose signed timestamp is too old (Stripe's libraries default to five minutes) to block replays. Return 2xx quickly and push the work to a queue, since slow handlers cause timeouts and more retries. In the worker, do not trust the order of events: either fetch the latest object from the provider's API, or apply transitions through a state machine that ignores moves backwards, such as a late "processing" event after "succeeded".

• Deduplicate by event ID with a unique constraint.
• Exempt the webhook route from CSRF protection, but never from signature checks.
• Alert when the endpoint returns non-2xx responses, before retries run out.

09Disputes and chargebacks

A chargeback happens when a cardholder asks their bank to reverse a payment: fraud, an item not received, or "not as described". The provider debits the disputed amount plus a dispute fee from your balance and opens a dispute with a deadline for evidence. Evidence that wins is specific: delivery confirmation with the address, signed receipts, logs showing the customer's account and device, refund policy accepted at checkout, and prior communication. 3-D Secure authentication usually shifts liability for fraud disputes to the issuer, but not for "item not received" disputes. Card networks monitor merchants' dispute ratios, and staying above their thresholds leads to fines or losing card acceptance. Prevention matters more than winning: a clear statement descriptor, fast refunds for genuine complaints, and fraud screening on risky orders.

10Securing the payment page under PCI DSS 4.0.1

Even when card fields live in a provider's iframe, attackers target the page around it: a compromised script can replace the iframe with a fake form or overlay it (often called e-skimming or Magecart-style attacks). PCI DSS 4.0.1 requirement 6.4.3 asks for an inventory of every script on payment pages with a justification and an integrity method, and 11.6.1 asks for a mechanism that detects unauthorised changes to those pages and their security headers. In the January 2025 revision of SAQ A, these two items were replaced by an eligibility criterion: the merchant must confirm their site is not susceptible to attacks from scripts, and the Council's guidance says the 6.4.3 and 11.6.1 techniques are the way to show it. In practice: few scripts on checkout, a strict Content Security Policy, Subresource Integrity for static files and change monitoring.

1# nginx: strict CSP on checkout pages (adjust to your provider's documented domains)
2location /checkout {
3  add_header Content-Security-Policy "default-src 'self'; script-src 'self' https://js.stripe.com; frame-src https://js.stripe.com https://hooks.stripe.com; connect-src 'self' https://api.stripe.com; img-src 'self' data:; report-to csp" always;
4  add_header Reporting-Endpoints 'csp="https://example.com/csp-reports"' always;
5  try_files $uri /index.php?$query_string;
6}