Checkout & Payments

Section 1

What it is

Checkout & Payments is the platform's acceptance stack: five repos cooperating so that a merchant's server, a shopper's browser and Adyen each see exactly what they are allowed to see.

The design principle is a single sentence: every money decision is made on the server before the browser is involved. The merchant's server, holding an sk_ secret key, creates a checkout session; that call resolves and freezes the split plan for all eight payment methods into CheckoutSession.splitsSnapshot and returns a single-use cs_ token plus the merchant's pk_ publishable key. The browser — whether the embeddable web SDK or a hosted page — presents that token pair to the /sdk/checkout surface, where the backend injects the amount and the split plan itself. The browser chooses a payment method; it can never choose a price.

After authorisation the story becomes asynchronous: Adyen's webhooks land at the dedicated ummah-platform-webhook ingress (HMAC-verified, persisted, deduplicated), ride the BullMQ queue webhook-in.adyen, and the worker walks the Transaction through its lifecycle — settlement is inferred from Adyen's booked split legs, not from any settlement webhook.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart LR
  MS["Merchant server
sk_ key"] -->|"POST /v1/checkout/sessions"| SES["CheckoutSession
splitsSnapshot · 8 FeeMethods"]
  SES -->|"single-use cs_ + pk_"| BR["Shopper browser
Adyen Web SDK"]
  BR -->|"POST /sdk/checkout/payments"| PAY["PaymentsService
amount + splits injected"]
  PAY -->|"POST /payments"| AD["Adyen
authorise + auto-split"]
  AD -.->|"webhooks · queue webhook-in.adyen"| WK["Worker
lifecycle + reconciliation"]
  WK -->|"booked legs sum complete"| FIN["Transaction SETTLED"]
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;
  class MS sub
  class SES,PAY,WK ummah
  class BR plain
  class AD adyen
  class FIN sub

ummah-platform-backend/src/modules/checkout/checkout.controller.ts:24-38 · checkout.service.ts:91-99 · sdk.controller.ts:17-62 · prisma/schema.prisma:1052,1149,1637

Section 2

The vocabulary

Twelve terms carry this whole page. Economics terms (rates, legs, bearers) live on Pricings, Splits & Fees.

Section 3

The payment flow

One session, two authenticated surfaces, one asynchronous truth. This is the canonical card payment from POST /v1/checkout/sessions to SETTLED.

3a · Creating the session (server side)

POST /v1/checkout/sessions sits behind ApiKeyGuard and @Idempotent() (optional Idempotency-Key header, replayed for 24 hours, 422 if the same key arrives with a different body). CheckoutService.createSession then:

• Gates the merchant — gate.assertOperational — and resolves the payee: a Client passing onBehalfOfMerchantId creates the session for one of its sub-merchants.
• Refuses unsplittable stores — assertStoreIsSplit requires splitProfileId, adyenStoreId and adyenBalanceAccountId, erroring with code store_not_split. An unconfigured store would silently book 100% of the funds to Ummah's liable balance account.
• Provisions balance accounts lazily — ensureBalanceAccount for the payee store, the Client store, and any tip beneficiary.
• Freezes pricing — buildSnapshot loops the 8 FeeMethods, calling FeeResolverService.resolvePaymentFee then AdyenSplitService.buildResolvedSplits per method, and stores the result as splitsSnapshot.
• Returns the single-use cs_ token and the pk_ publishable key for the browser.

3b · Paying in the browser

The browser surface is four routes on /sdk/checkout, all guarded by PublishableSessionGuard and the domain-allowlist origin interceptor. GET client-key hands the Adyen Web client key and environment; POST paymentMethods proxies Adyen's method list for the session's store; the Adyen Web component mounts the card form and its BIN lookup reports the brand as the shopper types. On POST payments, PaymentsService.payments derives feeMethod = brandToFeeMethod(...) from that pre-authorisation hint, picks snapshot.byMethod[feeMethod] ?? byMethod['OTHER'], upserts the Transaction (INITIATED, splitsApplied recorded) and only then calls Adyen — amount from snapshot.totalChargeMinor, store set to adyenStoreId, idempotency key pay-<sessionId>. 3DS2 runs natively in the component where possible; challenge and redirect flows finish through POST payments/details, which feeds the same applyPaymentResult.

The embeddable SDK (ummah-platform-web-sdk) wraps all of this as a React <UmmahCheckout> and a framework-agnostic mountUmmahCheckout(el, opts) — card plus Apple Pay and Google Pay, brand detection for per-method pricing, native 3DS2 in-component with a full-page redirect helper, and an environment switch of 'test'|'live' choosing the API host. The bundled Adyen Web library is invisible to integrators.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13px","primaryColor":"#FBE5D6","primaryTextColor":"#00273A","primaryBorderColor":"#E86C2B","lineColor":"#8195A1","actorBkg":"#FFFFFF","actorBorder":"#D2D8DE","actorTextColor":"#00273A","actorLineColor":"#D2D8DE","signalColor":"#33505F","signalTextColor":"#33505F","activationBkgColor":"#FBE5D6","activationBorderColor":"#E86C2B","noteBkgColor":"#FEF3DC","noteBorderColor":"#E8D5A8","noteTextColor":"#00273A","labelBoxBkgColor":"#F1F4F8","labelBoxBorderColor":"#D2D8DE","loopTextColor":"#33505F"},"sequence":{"mirrorActors":false,"actorMargin":46,"messageMargin":30,"boxMargin":8}}}%%
sequenceDiagram
  participant M as Merchant server
  participant B as Shopper browser
  participant U as Ummah backend
  participant A as Adyen
  participant W as Worker
  M->>U: POST /v1/checkout/sessions
  Note over U: assertStoreIsSplit · buildSnapshot
8 FeeMethod plans frozen into splitsSnapshot
  U-->>M: single-use cs_ token + pk_ key
  M-->>B: page mounts SDK with pk_ + cs_
  B->>U: POST /sdk/checkout/paymentMethods
  U->>A: /paymentMethods for the session store
  A-->>U: available methods
  U-->>B: card form mounts · BIN lookup hints brand
  B->>U: POST /sdk/checkout/payments with brand hint
  Note over U: feeMethod = brandToFeeMethod(hint)
Transaction INITIATED · splitsApplied recorded
  U->>A: /payments — amount injected from snapshot
splits sent only for profile-less stores
  alt 3DS2 challenge or redirect
    A-->>U: action
    U-->>B: SDK handles action
    B->>U: POST /sdk/checkout/payments/details
    U->>A: /payments/details
  end
  A-->>U: resultCode Authorised
  U-->>B: success · Transaction AUTHORIZED
  A--)W: AUTHORISATION + balancePlatform.transfer webhooks
  Note over W: HMAC-verified at ingress, deduped,
queued on webhook-in.adyen
  W->>W: reconcileSplits — booked legs vs mirror → SETTLED

ummah-platform-backend/src/modules/checkout/checkout.controller.ts:24-41 · checkout.service.ts:91-99,489-561 · sdk.controller.ts:17-62 · payments.service.ts:129-134,199-263,303-319 · common/interceptors/idempotency.interceptor.ts:20-60 · ummah-platform-web-sdk/src/index.ts · src/mount.ts

Section 4

Where splits attach

This page tracks where the split plan touches the payment flow; the economics — rates, legs, bearers, worked numbers — belong to Pricings, Splits & Fees.

Splits attach at four moments:

• Session create — the freeze. buildSnapshot resolves a full split plan per FeeMethod and freezes all eight into splitsSnapshot, so a rate change after session create cannot alter an in-flight payment.
• Pay time — the selection. PaymentsService.payments picks the plan for the BIN-lookup brand hint. For a store carrying a SplitProfile the request sends no splits[] — Adyen auto-splits from the store's own split configuration — and the platform records a locally recomputed mirror (buildProfileSplits, banker's rounding, chosen by splitGroupFor(feeMethod): VISA_MC / AMEX / REMAINING). Only profile-less stores send the frozen explicit legs.
• Capture time — the recompute. On a manual-capture hold, CapturesService re-records (and for explicit-splits payments re-sends) splits for the captured amount — Section 6.
• Settlement — the audit. The worker's TransferEventService.reconcileSplits compares Adyen's booked platformPayment transfer legs against splitsApplied; a complete matching set promotes the transaction to SETTLED, a divergence stamps splitsMismatch and alarms the back office.

ummah-platform-backend/src/modules/checkout/payments.service.ts:184-232,255-263,404-461,672-676 · core/adyen/adyen-split.service.ts:259-350,498-619 · ummah-platform-worker/src/modules/webhooks-in/transfer-event.service.ts:246-470

Section 5

Transaction lifecycle

Ten statuses, all webhook-driven after the initial upsert. There is no settlement webhook: SETTLED is inferred when Adyen's booked split legs sum exactly to the captured or authorised amount.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart LR
  I["INITIATED"] -->|"AUTHORISATION ok"| AU["AUTHORIZED"]
  I -->|"AUTHORISATION failed"| FA["FAILED"]
  AU -->|"CAPTURE webhook"| CA["CAPTURED"]
  AU -->|"manual capture submitted"| CP["CAPTURE_PENDING"]
  CP -->|"CAPTURE ok"| CA
  CP -->|"CAPTURE failed"| EX["EXPIRED"]
  AU -->|"CANCELLATION"| CN["CANCELLED"]
  CA -->|"legs sum complete"| SE["SETTLED"]
  AU -->|"legs complete first"| SE
  SE -->|"CHARGEBACK"| DI["DISPUTED"]
  DI -->|"won or reversed"| SE
  SE -->|"refundedMinor reaches total"| RF["REFUNDED"]
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;
  class I,CN,RF plain
  class AU,CP,EX warn
  class CA,SE sub
  class FA,DI danger

ummah-platform-worker/src/modules/webhooks-in/adyen-webhook.service.ts:143-201,210-348 · transfer-event.service.ts:246-470,313-366 · ummah-platform-backend/src/modules/checkout/payments.service.ts:404-461

Section 6

Holds & capture

A session (or an "authorise only" payment link) with captureMode MANUAL pins additionalData.manualCapture 'true' on the Adyen call: the authorisation becomes a hold, displayed with authorisedUntil of roughly seven days — a display value, not an enforced expiry.

The split-aware path is POST /api/portal/payments/:id/capture or its admin twin, both landing in CapturesService.capture. It validates hard: loadHold rejects anything whose captureMode is not MANUAL, the row must be AUTHORIZED, the amount must not exceed the authorisation, and there is one capture per authorisation. Then splitsForCapture branches:

• Profile store — re-record buildProfileSplits(capturedAmount) using the transaction's scheme group, and send nothing: Adyen's store split configuration recomputes the split itself at capture.
• Explicit-splits payment — scaleSplitsProportionally produces pro-rata legs which are recorded and sent as splits[] on POST /payments/{psp}/captures, because a capture whose amount differs from the authorisation, sent without splits, books everything to the liable account.

Worked shape: a £100.00 hold captured at £60.00 re-records the mirror for £60.00 (with splitsReconciledAt nulled and splitsMismatch cleared), transitions to CAPTURE_PENDING under idempotency key capture-<txnId>, and lets the CAPTURE webhook decide the truth. A submit failure restores AUTHORIZED. Releases go through CapturesService.release, confirmed by the CANCELLATION webhook.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart TD
  H["AUTHORIZED hold
additionalData.manualCapture true"] --> SAFE["Portal / admin capture
CapturesService.capture"]
  H --> BY["sk_ POST /v1/payments/:id/capture"]
  SAFE --> Q{"store has a
SplitProfile?"}
  Q -->|"yes"| MIR["re-record buildProfileSplits
send no splits"]
  Q -->|"no"| SCL["scaleSplitsProportionally
record and send splits"]
  MIR --> CP2["CAPTURE_PENDING
idempotency capture-txnId"]
  SCL --> CP2
  CP2 --> AD2["Adyen POST captures"]
  BY --> RAW["raw adyen.checkout.capture
no guard · no splits · no mirror"]
  AD2 -.->|"CAPTURE webhook"| OK2["CAPTURED → SETTLED"]
  RAW -.->|"CAPTURE webhook"| OK2
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;
  class H warn
  class SAFE ummah
  class Q,MIR,SCL plain
  class CP2 warn
  class AD2 adyen
  class BY,RAW danger
  class OK2 sub

6a · The sk_ bypass

POST /v1/payments/:id/capture (and its sibling POST /v1/payments/:id/cancel) on the merchant API surface still route to PaymentsService.capture, which submits adyen.checkout.capture(pspReference, ...) directly with reference cap-<txn.id> — no MANUAL/AUTHORIZED guard, no splits sent, no splitsApplied re-record, no CAPTURE_PENDING transition, and no Adyen idempotency key. A partial capture through this route on an explicit-splits (profile-less) payment makes Adyen book the entire captured amount to the liable account, while the recorded mirror stays at the authorisation amount.

ummah-platform-backend/src/modules/captures/captures.service.ts:60-146,216-297 · portal-captures.controller.ts:20-33 · admin-captures.controller.ts:21-35 · checkout.controller.ts:90-106 · payments.service.ts:608-650

Section 7

Saved cards & merchant-initiated charges

Cards are tokenised inside the normal checkout; charging them later is a first-class server-side flow with its own cap — and its own recorded-rate gap.

Tokenisation during checkout

A session carrying customerId and savePaymentMethod adds shopperReference and storePaymentMethod to the Adyen call. The token lands twice over: a successful AUTHORISATION carries additionalData['recurring.recurringDetailReference'], and the RECURRING_CONTRACT webhook upserts the StoredPaymentMethod against the Customer. Merchants browse chargeable cards through the checkout service's saved-card lookup and the /v1/customers surface.

MIT charges — POST /v1/charges

Behind sk_ auth and @Idempotent(), CheckoutService.mitCharge reuses the entire session machinery — a real CheckoutSession with a frozen splitsSnapshot — then pays as ContAuth with paymentMethod {type:'scheme', storedPaymentMethodId}. Merchant.mitAmountCapMinor caps the amount (0 = uncapped). Subscription billing drives the same path: the worker's subscription-tick queue calls the backend's signed internal endpoint (X-Internal-Signature, idempotent per billing period), which lands in mitCharge.

The gap: that payment method object has no brand, so brandToFeeMethod('scheme') resolves to OTHER and the mirror records REMAINING-group rates regardless of the stored card's real scheme — while Adyen books the real scheme's rule. On every per-scheme-priced profile store, MIT charges rely on the splitsMismatch alarm rather than a correct mirror.

7a · PM_UPDATE zero-value sessions

Card refresh without a charge uses a session of purpose PM_UPDATE: the snapshot is stored empty (byMethod: {}) and PaymentsService.pmUpdatePayments sends amount 0 with storePaymentMethod and recurringProcessingModel 'Subscription'. A store is still required — store-less payments 403 on platform accounts — but there are deliberately no splits and no Transaction row: nothing to account for, nothing to reconcile. Card-update links (/u/[token]) and subscription links both ride this.

ummah-platform-backend/src/modules/checkout/checkout.controller.ts:40-57 · checkout.service.ts:200-268,278-365 · payments.service.ts:272-291,331-385 · ummah-platform-worker/src/workers/subscription-tick.processor.ts:86-130 · ummah-platform-worker/src/modules/webhooks-in/adyen-webhook.service.ts:161

Section 8

Hosted checkout pages

The Next.js app ummah-platform-checkout serves three token-addressed experiences, all funnelling into the same session machinery as the SDK.

All three tokens are stored only as environment-bound peppered hashes — the raw token is returned once at creation and is irrecoverable, so "re-copy the URL" is really rotation: POST :id/regenerate mints a fresh token and the old URL stops working. Link redemption requires status ACTIVE. The shared HostedCheckout component wraps the same checkout-controller core the web SDK uses, so splits, 3DS2 and lifecycle behave identically to Section 3.

ummah-platform-checkout/app/l/[token]/LinkCheckout.tsx · app/sub/[token]/SubscribeFlow.tsx · app/u/[token]/UpdateCard.tsx · ummah-platform-backend/src/modules/payment-links/payment-links.service.ts:38-133,229-289 · public-payment-links.controller.ts:21-28 · pm-update-public.controller.ts:21-39 · subscription-links/public-subscribe.controller.ts:24-51

Section 9

Implementation notes

Every endpoint in the acceptance stack, by surface, with its guard. The /v1 surface additionally sits behind ApiExposureGuard — anything absent from the exposure catalog 404s.

Data model notes

• CheckoutSession — status, purpose, splitsSnapshot (Json), customerId, savePaymentMethod; single-use cs_ token.
• Transaction — status, feeMethod, splitsApplied / splitsReconciledAt / splitsMismatch, capturedMinor, refundedMinor, pspReference, merchantReference (<merchantSlug>-<ref>, capped at 80 chars). PaymentEvent rows keep the raw webhook timeline.
• IdempotencyKey — store-and-replay for @Idempotent endpoints: scoped by method, path, actor and body hash; 24 h TTL; responses persisted only on success so failures stay retryable; fails open on infrastructure errors.
• Adyen idempotency — pay-<sessionId> on /payments, capture-<txnId> on split-aware captures; the sk_ capture bypass sends none.
• AdyenWebhookEvent — the ingress ledger: HMAC-verified, unique dedupeKey (eventCode:pspReference:success for classic items), BullMQ jobId = hash of the dedupe key, processedAt re-checked by the worker.

ummah-platform-backend/src/modules/api-keys/api-key.guard.ts:39-84 · api-catalog/api-exposure.guard.ts · common/interceptors/idempotency.interceptor.ts:20-60 · prisma/schema.prisma:833,1052,1178-1191,1273 · ummah-platform-webhook/src/webhooks/ingress.service.ts:18-144 · payments.service.ts:719-725

Section 10

Gaps & recommendations

Everything below is verified against current code, ordered by how much money it can misplace.