Reconciliation & Financial Integrity

Section 1

The proof machine

There is no settlement webhook. A comment in the worker spells it out: Adyen's SettleScheduled and SettledAcquirer states track the acquirer leg inside Customer Area and are never webhooked per payment. Settlement on Ummah is therefore an inference — a conclusion the platform is only allowed to draw once a complete, matching set of booked split legs has arrived.

The mechanism has two independently written ledgers. At pay time (and again at capture) the backend writes down the split it expects Adyen to book — the mirror, Transaction.splitsApplied, computed with the same half-to-even rounding Adyen uses so arithmetic can never cause a false alarm. Meanwhile Adyen books the real split via the store's attached split configuration and streams each booked leg back as a balancePlatform.transfer.* webhook, which the worker persists as AdyenTransferLeg rows. The worker's reconcileSplits sits between the two and issues the verdict: agreement promotes the transaction to SETTLED and accrues the rolling reserve; divergence stamps a splitsMismatch and wakes the admins. What the split rates are and who sets them is the territory of Pricings, Splits & Fees — this page is about proving the booked money matches them.

%%{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
  PAY["Pay time
POST /payments"]:::ummah --> MIR["Transaction.splitsApplied
the mirror, half-to-even"]:::ummah
  CAPT["Capture re-record
CapturesService"]:::ummah --> MIR
  ADY["Adyen auto-split
store splitConfiguration"]:::adyen --> WH["balancePlatform.transfer.*
webhooks"]:::adyen
  WH --> LEG["AdyenTransferLeg
one row per booked leg"]:::plain
  MIR --> REC{"reconcileSplits"}:::ummah
  LEG --> REC
  REC -->|"buckets agree"| OKN["SETTLED · splitsReconciledAt
reserve accrual"]:::sub
  REC -->|"buckets diverge"| MMN["splitsMismatch
audit + admin alarm"]:::danger
  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;

ummah-platform-worker/src/modules/webhooks-in/transfer-event.service.ts:45-89 · ummah-platform-backend/src/modules/checkout/payments.service.ts:199-232 · ummah-platform-backend/src/core/adyen/adyen-split.service.ts:498-619 · ummah-platform-backend/prisma/schema.prisma:1185-1191,1477-1495

Section 2

The vocabulary

Ten identifiers carry the whole feature. Everything below is a real column, method, or queue name — verbatim from the code.

Section 3

Per-payment reconciliation

From the moment a payment authorises, booked legs stream in over seconds. The worker refuses to judge until it has seen them all — then it judges hard.

1. The mirror is written first. PaymentsService.payments upserts the Transaction (status INITIATED) with splitsApplied = buildProfileSplits(...) before calling Adyen. Profile stores send no splits[] — Adyen splits automatically from the store's attached configuration — so the mirror legs (seller-split, ummah-fixed, ummah-variable, client-fixed, client-variable, plus the adyen-fee 0-marker) are a prediction of Adyen's booking, computed with the same half-to-even rounding.
2. Adyen books the real legs. Seller remainder to the store's balance account, Commission (no account) to the liable account, AdditionalCommission to the parent Client's account, and its real processing fee as a PaymentFee leg per feesBorneBy.
3. Each leg arrives as a webhook. balancePlatform.transfer.created/updated events with category platformPayment are upserted into AdyenTransferLeg, keyed by adyenTransferId and linked via pspPaymentReference.
4. reconcileSplits buckets and waits — the mechanism below.

Bucketing & the sum gate

Only incoming legs with status booked or captured count — outgoing legs are refund reversals and belong to Refunds & Approvals. Three buckets are formed: BalanceAccount legs → seller; Commission without an account → commission; Commission with an account → additionalCommission, because Adyen books accounted Commission as AdditionalCommission (the mirror's client-fixed/client-variable legs are counted the same way at transfer-event.service.ts:309). PaymentFee legs are excluded from the verdict entirely: the mirror holds a £0.00 marker while Adyen books its real fee — which lands in AdyenTransferLeg but is never decomposed or used (see Pricings, Splits & Fees on why that starves cost-plus pricing of actuals).

No verdict is issued until the counted buckets sum to capturedMinor || amountMinor. Legs stream in over seconds, and a partial bucket is not a wrong bucket — this sum gate is the false-alarm fix of 2026-07-20. Because both sides always total the full payment amount, the gate is purely a completeness test; the real comparison is the per-bucket one that follows it.

%%{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 TB
  LEGS["Incoming platformPayment legs
status booked or captured"]:::adyen --> FXQ{"Leg currency =
payment currency?"}:::plain
  FXQ -->|"no — FX conversion"| FXS["SETTLED unverified
reserve accrual skipped"]:::danger
  FXQ -->|"yes"| BUCK["Bucket by type
seller · commission · additionalCommission"]:::ummah
  BUCK --> GATE{"Buckets sum to
capturedMinor or amountMinor?"}:::plain
  GATE -->|"not yet"| WAITN["No verdict
legs still streaming"]:::warn
  GATE -->|"complete"| CMP{"Each bucket equals
the splitsApplied mirror?"}:::ummah
  CMP -->|"clean"| OKN["SETTLED + splitsReconciledAt
Reserve.heldMinor accrues"]:::sub
  CMP -->|"diverges"| MMN["splitsMismatch diffs
notifyAdmins split.mismatch"]:::danger
  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;

On a complete set the transaction is promoted to SETTLED (fixing capturedMinor for immediate captures) and the rolling reserve accrues — an atomic, once-only increment of Reserve.heldMinor by rollingPercentBps of the seller leg. Then the verdict is stamped: splitsReconciledAt when clean, or splitsMismatch with the diffs plus an error log, a transaction.split_mismatch audit entry, and a notifyAdmins('split.mismatch') alarm when not.

A worked verdict — TEST PSP TZGGMW3F9CWD2HV5

A £100.00 sub-merchant payment on a profile priced at 1% + £1.00 commission with a 2% additionalCommission for the parent Client (rates are illustrative of that TEST profile — headline pricing lives in Pricings, Splits & Fees):

Buckets sum to the payment amount, each bucket equals its mirror counterpart, so the row is promoted SETTLED, splitsReconciledAt is stamped, and the reserve accrues its percentage of the £96.00 seller leg. Zero-value legs (here a would-be client-fixed) are simply not emitted.

Capture re-runs the judgement

A manual-capture hold changes the amount being judged. CapturesService re-records the mirror for the captured amount — nulling splitsReconciledAt and clearing any splitsMismatch — and moves the row to CAPTURE_PENDING. When the CAPTURE webhook confirms success, the handler calls reconcileForPsp to re-run the whole verdict against capturedMinor. A row whose legs already promoted it to SETTLED is never downgraded. The one door that dodges all of this is the sk-key POST /v1/payments/:id/capture, which captures at Adyen raw — no re-record, no status guard — leaving a stale mirror that only the mismatch alarm will catch (Section 7).

The FX blind spot

When the settled currency differs from the payment currency (found live 2026-08-18), reconcileSplits has no Adyen FX rate to verify against: the transaction is promoted to SETTLED with no amount verification, no alarm, and no reserve accrual — Reserve.heldMinor is single-denomination, so cross-currency seller legs simply never feed it.

ummah-platform-worker/src/modules/webhooks-in/transfer-event.service.ts:246-470 · ummah-platform-backend/src/modules/checkout/payments.service.ts:199-232 · ummah-platform-backend/src/modules/captures/captures.service.ts:88-146 · ummah-platform-worker/src/modules/webhooks-in/adyen-webhook.service.ts:328-333 · ummah-platform-worker/src/core/adyen/adyen-split.service.ts:474-595

Section 4

The daily 02:00 run

Per-payment reconciliation is event-driven; the daily run is the safety net underneath it — a BullMQ repeatable job (jobId reconciliation-daily) that sweeps for everything the event stream should have resolved but did not. Staff can also trigger it by hand: POST /api/admin/reconciliation/run enqueues trigger:'MANUAL' on the same queue, with an hour-bucketed jobId that collapses duplicate clicks.

Each ledger sweep (checks 1–6) records up to 10 sample ids into the run's checks JSON so an operator can jump straight to offending rows. The seller net used by the re-target is computed from splitsApplied Commission legs — amount minus refunds minus commission of both kinds.

%%{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 TB
  TRIG["02:00 UTC repeatable job
or manual admin run"]:::ummah --> RUNROW["ReconciliationRun row
trigger SCHEDULED or MANUAL"]:::plain
  RUNROW --> SWEEPS["Six ledger sweeps
splits-mismatched · awaiting-stale over 24 h
txns, refunds, payouts over 3 d · recoveries over 24 h"]:::warn
  SWEEPS --> BAL{"balance-refresh
refreshAll from Adyen"}:::adyen
  BAL -->|"every BA failed"| DEG["DEGRADED
Adyen unreachable"]:::danger
  BAL -->|"refreshed"| RET["reserve-retarget
informational only"]:::ummah
  RET --> ROLL{"Rollup verdict"}:::plain
  DEG --> ROLL
  ROLL -->|"all clean"| OKV["OK"]:::sub
  ROLL -->|"any check trips"| AL["MISMATCH or DEGRADED
notifyAdmins reconciliation.alert"]:::danger
  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;

ummah-platform-worker/src/workers/reconciliation.processor.ts:16-294 · ummah-platform-worker/src/workers/reconciliation.logic.ts:15-31 · ummah-platform-backend/src/modules/reconciliation/reconciliation.controller.ts:15-59

Section 5

Mismatch lifecycle

A mismatch is deliberately a dead end for automation: the platform records exactly what disagreed, alarms once, and then waits for a human. Nothing anywhere auto-corrects a splitsMismatch.

%%{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 AD as Adyen Balance Platform
  participant W as Worker · TransferEventService
  participant TX as Transaction row
  participant OPS as Ops · back-office
  AD-->>W: balancePlatform.transfer.updated · platformPayment leg
  W->>TX: upsertLeg → AdyenTransferLeg
  W->>W: reconcileSplits · buckets vs splitsApplied
  alt buckets diverge from the mirror
    W->>TX: splitsMismatch = diffs + ours + adyen + legCount
    W-->>OPS: audit transaction.split_mismatch + notifyAdmins split.mismatch
    Note over W: redelivered identical verdicts never re-alarm
    OPS->>TX: GET /api/admin/reconciliation/mismatches
    Note over TX,OPS: never auto-corrected — cleared only by manual action or a capture re-record
  else clean
    W->>TX: SETTLED + splitsReconciledAt + reserve accrual
  end
  AD-->>W: CAPTURE webhook · success
  W->>W: reconcileForPsp re-runs the verdict for the captured amount

The back-office panel is the ops surface for all of it — five read endpoints under /api/admin/reconciliation (all RequireScope('STAFF')): summary gives the mismatched count, mirrors awaiting a verdict for over 15 minutes, and the clean count over the last 30 days; mismatches returns up to 100 transactions with the full splitsMismatch payload, both sides and the diffs; awaiting lists the not-yet-judged; runs and runs/latest expose the daily-run history. A lingering mismatch also keeps every subsequent ReconciliationRun at MISMATCH via check 1 — the system nags until someone acts.

ummah-platform-backend/src/modules/reconciliation/reconciliation.service.ts:41-117 · ummah-platform-worker/src/modules/webhooks-in/transfer-event.service.ts:424-466

Section 6

Implementation notes

Everything reconciliation-facing lives under one admin module in the backend plus two worker processors; the webhook repo feeds them.

ummah-platform-backend/src/modules/reconciliation/reconciliation.controller.ts:15-59 · ummah-platform-backend/src/modules/reconciliation/reconciliation.service.ts:41-117 · ummah-platform-webhook/src/webhooks/ingress.service.ts:50-107 · ummah-platform-worker/src/workers/webhook-in-adyen.processor.ts:56-62 · ummah-platform-backend/prisma/schema.prisma:1185-1191,1477-1495

Section 7

Gaps & recommendations

The proof machine is genuinely good at what it checks. These are the places where it checks nothing — ordered by how much money is at stake.