Payment Links

Section 1

What a payment link is

A payment link is a stored request to be paid — a PaymentLink row owned by a merchant, pointing at one of its stores, carrying an amount, line items and a capture mode — addressed by an unguessable pl_ token that exists in raw form only in the moment of creation. The link itself moves no money.

When a donor opens the hosted page, the platform mints a completely normal checkout session from the link's stored parameters. Everything downstream — the frozen split plan, the browser SDK surface, the Adyen /payments call, the webhook-driven settlement — is the standard card path, indistinguishable from a session a merchant's own server created via POST /v1/checkout/sessions. The economics (who earns what on each payment) are frozen at session creation and are the subject of Pricings, Splits & Fees; this page does not re-explain them.

Three properties define the feature's character: the token is stored only as an environment-bound peppered hash (so it can be verified but never re-read); the link is reusable until paid, with the PAID flip evaluated lazily on read; and "re-copy the URL" does not exist — the only recovery is regeneration, which mints a new token and silently kills the old URL.

%%{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
  create["Merchant creates link
portal or v1 surface"]:::ummah
  raw["Raw pl_ token — shown once
URL and QR shared"]:::ummah
  active["ACTIVE
reusable until paid"]:::plain
  paid["PAID
flip is lazy, on read"]:::sub
  regen["Regenerated
new token minted"]:::warn
  gone["Deactivated or expired
redemption refused"]:::danger
  create --> raw --> active
  active -->|"authorised transaction
carries its paymentLinkId"| paid
  active -->|"POST :id/regenerate"| regen
  regen -->|"fresh URL — old one dies"| active
  active -->|"DELETE :id, or
paymentLinkExpiryDays elapse"| gone
  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-backend/src/modules/payment-links/payment-links.service.ts:38-133 · payment-links.service.ts:229-252 · payment-links.service.ts:268-289 · ummah-platform-checkout/app/l/[token]/page.tsx

Section 2

The vocabulary

Nine terms carry this whole feature. All names are verbatim from the code.

Section 3

Create & share

Two front doors, one service. The portal's payment-links screen calls POST api/portal/payment-links; API-first merchants use the v1/payment-links surface behind an sk_ key (gated, like all of /v1, by ApiKeyGuard and the ApiExposureGuard allowlist).

Creation is where the token's whole security story happens. generatePaymentLinkToken(pepper) returns a {token, hash} pair; the service persists only the hash and returns the raw pl_ token — embedded in the hosted URL — exactly once. The portal presents the URL for copying and as a QR code for print and screen sharing. There is no "show me the link again": because the raw token is irrecoverable, the portal's re-copy affordance is regenerate, which mints a fresh token and hash. The moment the new hash lands, the old URL — on posters, in WhatsApp messages, in QR codes already printed — resolves to nothing.

Links do not live forever: the platform-level paymentLinkExpiryDays setting (1–365 days, held in PlatformSetting and editable from the back-office settings screen) bounds how long a link remains redeemable.

%%{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
  mint["generatePaymentLinkToken
with the environment pepper"]:::ummah
  raw2["raw pl_ token
returned exactly once"]:::ummah
  store["PaymentLink.tokenHash
raw token never stored"]:::plain
  res["GET checkout/links/:token
re-hash incoming token, look up"]:::plain
  rot["POST :id/regenerate
new pair replaces the hash"]:::warn
  dead["old URL, and any token from
another environment — no match"]:::danger
  mint -->|"returns"| raw2
  mint -->|"persists"| store
  raw2 -->|"donor opens URL"| res
  res -->|"hash lookup"| store
  rot -->|"overwrites"| store
  rot -->|"previous token"| dead
  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-backend/src/modules/payment-links/payment-links.service.ts:38-133 · ummah-platform-backend/src/modules/payment-links/portal-payment-links.controller.ts:26-83 · ummah-platform-backend/src/modules/api-catalog/api-exposure.guard.ts

Section 4

Donor redemption

The donor opens /l/[token] on the hosted Next.js checkout app. Two public, unauthenticated backend endpoints do all the work: one resolves the link, one mints the session. From there it is the standard checkout path.

First, the page calls GET checkout/links/:token for the link details plus the merchant's branding (the hosted page is already branded per merchant, even while the portal branding screen remains a placeholder). Then it calls POST checkout/links/:token/session — proxied through the app's own app/api/links/[token]/session route — which runs PaymentLinksService.redeem: the token hash is resolved, the link must be ACTIVE, and a normal session is minted via CheckoutService.createSession with the link's store, amount, line items and capture mode, plus metadata {paymentLinkId}.

Because it is the real createSession, the real gates run: gate.assertOperational, and assertStoreIsSplit — a store missing any of splitProfileId, adyenStoreId or adyenBalanceAccountId refuses payment with error code store_not_split rather than silently booking everything to the platform's liable account. The per-method split plan is frozen into splitsSnapshot exactly as described in Pricings, Splits & Fees. The shared HostedCheckout component then drives the browser surface: POST sdk/checkout/paymentMethods and POST sdk/checkout/payments under PublishableSessionGuard (headers X-Ummah-Publishable-Key + X-Ummah-Session), with amount and splits injected server-side from the frozen session. Success, or 3DS completion via POST sdk/checkout/payments/details, lands the donor on /l/[token]/return.

%%{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 D as Donor browser
  participant C as Checkout app
  participant B as Backend
  participant A as Adyen
  D->>C: open /l/[token]
  C->>B: GET checkout/links/:token
  B-->>C: link details + branding
  C->>B: POST checkout/links/:token/session
  Note over B: redeem — link must be ACTIVE
createSession freezes splitsSnapshot
metadata.paymentLinkId, link captureMode
  B-->>C: cs_ session token + pk_ key
  D->>B: POST sdk/checkout/payments
  Note over B: amount + splits injected
server-side from the session
  B->>A: POST /payments
  A-->>B: resultCode or 3DS action
  B-->>D: result, then /l/[token]/return
  A-->>B: AUTHORISATION webhook
  Note over B: Transaction AUTHORIZED —
next link read flips PAID

Reusable until paid

A link is not single-use by construction: every open mints a fresh session, and the link keeps resolving while ACTIVE. What ends its life as a payable object is the lazy PAID flip — on read, if any checkout session carrying its paymentLinkId has an authorised transaction, the status becomes PAID and redemption stops. Lazy means there is a window between authorisation and the next read in which a second donor with the page already open can also pay; nothing in the redemption path blocks the second session. Money that arrives through a link leaves through the ordinary path — see Refunds & Approvals.

ummah-platform-backend/src/modules/payment-links/public-payment-links.controller.ts:21-28 · payment-links.service.ts:229-252, 268-289 · ummah-platform-backend/src/modules/checkout/checkout.service.ts:91-99, 489-505, 525-561 · ummah-platform-checkout/app/l/[token]/LinkCheckout.tsx · ummah-platform-checkout/components/HostedCheckout.tsx

Section 5

Authorise-only links (pledge holds)

A link created with captureMode MANUAL takes a pledge rather than a payment: the donor's card is authorised, the funds are held, and nothing is captured until the merchant decides.

Mechanically, the link's capture mode flows onto the minted session, and the /payments call carries additionalData.manualCapture 'true'. The authorisation leaves the transaction AUTHORIZED with a display-only authorisedUntil of roughly seven days. From there the merchant captures through POST api/portal/payments/:id/capture (staff twin api/admin/payments/:id/capture), which is the split-aware path: CapturesService.capture validates AUTHORIZED + MANUAL, allows a single capture up to the authorised amount, recomputes the recorded splits for the captured amount, moves the row through CAPTURE_PENDING, and lets the CAPTURE webhook be the truth. Releasing the pledge instead books a cancellation, confirmed by the CANCELLATION webhook.

The trap: the sk-key surface still exposes POST /v1/payments/:id/capture, and it bypasses CapturesService entirely — a raw Adyen capture with no status or capture-mode guard, no splits sent, no re-record of the split mirror, and no Adyen idempotency key. A partial capture through that endpoint on an explicit-splits (profile-less) payment books the whole captured amount to Ummah's liable account. An API-integrated merchant capturing its link pledges is one innocent-looking call away from that. (/v1/payments/:id/cancel has the same relationship to the proper release path.)

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

Section 6

Regenerate, deactivate, expire

Three ways a URL stops working, with very different intents. Choosing the wrong verb is the most common self-inflicted "Link not found".

ummah-platform-backend/src/modules/payment-links/portal-payment-links.controller.ts:64-83 · payment-links.service.ts:229-252 · ummah-platform-backend/src/modules/settings/admin-settings.controller.ts:28-35 · prisma/schema.prisma:1139 (PlatformSetting)

Section 7

"Link not found", debugged

The hosted page has exactly one failure state. Whatever goes wrong — a regenerated token, a deactivated or expired link, a token pasted into the wrong environment, a misconfigured front-end build, an unreachable backend — the donor sees the same "Link not found". The page tells you nothing; the API tells you everything.

The environment binding deserves emphasis because it produces the most confusing incidents: a link minted against the TEST environment cannot resolve in LIVE, and vice versa. The pepper differs per environment, so the hash lookup simply finds no row — indistinguishable from a token that never existed. A demo link pasted into production material, or a LIVE QR code scanned against a staging build, dies silently.

The triage that works

Skip the page; interrogate the resolution endpoint directly against the environment the link should live in — for example curl https://api.dev.ummah.com/checkout/links/<token> for the dev environment. The status code is the only honest signal in the system:

• 200 — the link is fine; the problem is in front of it. Suspect the hosted app's build configuration: the checkout app must have its API host baked in at build time, and a known incident (fixed in commit df969cc) was exactly this — environment variables not baked into the Next.js production build, so every link on that deployment rendered "Link not found" while the API answered perfectly.
• Non-200 — the token really does not resolve here. In order of likelihood: the link was regenerated (the URL in hand predates the rotation), it was deactivated or has expired, or the token belongs to another environment. Check the portal's payment-links screen for the link's current status and creation environment before assuming a bug.

%%{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
  seen["Donor reports Link not found
page gives no reason, ever"]:::danger
  curl["curl the environment API directly
GET checkout/links/:token"]:::ummah
  ok["200 — link resolves"]:::sub
  bad["404 or error — token unknown here"]:::warn
  front["Front-end problem — API host not
baked into the hosted build"]:::warn
  cause["Token problem — regenerated,
deactivated, expired, or wrong environment"]:::danger
  seen --> curl
  curl -->|"200"| ok
  curl -->|"non-200"| bad
  ok --> front
  bad --> cause
  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-backend/src/modules/payment-links/public-payment-links.controller.ts:21-28 · ummah-platform-checkout/app/l/[token]/page.tsx · ummah-platform-checkout/app/api/links/[token]/session

Section 8

Implementation notes

Every endpoint the feature touches, with its guard. Names verbatim from the controllers.

Data model notes

• PaymentLink — payee store, amount, line items, captureMode, PaymentLinkStatus, tokenHash. The raw token has no column, by design.
• CheckoutSession — one per redemption attempt, carrying the frozen splitsSnapshot and metadata.paymentLinkId; the lazy PAID flip queries sessions by that metadata for an authorised Transaction.
• PlatformSetting — paymentLinkExpiryDays (1–365) governs expiry platform-wide; no per-link expiry field exists on the current surface.
• Siblings — subscribe links (/sub/[token]) and card-update links (/u/[token]) reuse the same peppered-token pattern; this page covers only payment links.

ummah-platform-backend/src/modules/payment-links/payment-links.service.ts:38-133, 229-289 · portal-payment-links.controller.ts:26-83 · public-payment-links.controller.ts:21-28 · ummah-platform-backend/prisma/schema.prisma:1052 (CheckoutSession), 1139 (PlatformSetting)

Section 9

Gaps & recommendations

Ranked by consequence: money risk first, then operational friction, then polish.