Ummah Passport Build Plan

One donor identity and one stored card, usable at every charity on Ummah. UK only, on the single Adyen merchant account. This is the plan to confirm before any code is written; it names the exact seams in the platform it builds on.

Status

Confirmed 2 Oct. POC built 3 Oct on passport-impl branches (local, unpushed) against a separate ummah_passport database. API spike and browser end-to-end both pass: one donor, one card, two charities, no re-entry.

Scope

United Kingdom, GBP, merchant account TrustXPayCOM. One Passport per donor, one region.

Basis

Platform code on development as of 2 Oct 2026, verified line by line.

Shape

Separate product: its own app and domain. Identity, cards, charities and payments all on Ummah.

What Passport is

A donor registers with Ummah once, verifies their email, and stores one card with a zero-value authentication. From then on, at any charity on the platform, they are recognised and give with a single confirmation. No card re-entry, no account per charity. Their receipts and giving history follow them rather than sitting with each charity.

Commercially it makes the donor Ummah's relationship as well as the charity's. That is the product; the payment rails underneath it already exist.

Boundaries you have set

• UK only. One Adyen merchant account, one token vault, one liable balance account. Multi-currency settlement is a separate workstream and does not change this plan.
• A separate product. Its own application and domain (working name passport.ummah.com), its own brand treatment, its own release cadence.
• Authenticated on Ummah. Donor accounts, sessions and credentials live in the Ummah backend under a new auth scope. No third-party identity provider in v1.
• Charities are Ummah merchants. Existing stores, balance accounts and split profiles. Nothing changes for a charity that never hears of Passport.
• Cards and payments on Ummah. Tokens in Adyen's vault under Ummah's merchant account, charged through the existing payment service with the existing splits.

Already there, and what gets built

Architecture: a hub with per-charity spokes

The one structural change is small and additive. A Passport account sits above the merchant-scoped customer records. Each charity keeps its own customer row for that donor, created the first time the donor interacts with it, and each row holds a mirror of the same Adyen token. Adyen holds one token; merchants see "their customer's saved card" exactly as they do today.

• PassportAccount is new: id (uuid v7), verified email (unique), display name, status, consent timestamps. Credentials are passkeys plus an email one-time code; there are no passwords.
• Customer gains one nullable column, passportAccountId. The existing unique constraint on merchant plus reference stays. Every existing customer row and token is untouched.
• StoredPaymentMethod does not change shape. For Passport cards the Adyen token is minted with shopperReference set to the account id. Each charity's customer row gets its own row for the same adyenStoredPaymentMethodId; the existing unique key on customer plus token already allows this.
• Why mirrors rather than re-scoping: subscriptions, dunning, merchant-initiated charging, portal customer pages and the worker's token persistence all key on a Customer today. Mirroring leaves every one of them working. Removing a Passport card disables all mirrors and revokes the token at Adyen once.

Flow A: first registration

1. EntryFrom the hosted checkout of any charity ("Save with Passport" at the end of a normal card payment), or directly on the Passport app.
2. IdentityEmail, then a six-digit code by email. Account created on first successful code. Passkey enrolment offered immediately after, and again on next sign-in if skipped.
3. CardReuse the existing zero-value flow with the Passport branch: amount 0, storePaymentMethod true, shopperInteraction Ecommerce, recurringProcessingModel CardOnFile, native 3DS preferred, shopperReference = account id. The spoke customer row for that charity is created first so the session carries a customerId.
4. TokenArrives on the Adyen webhook as today. The worker resolves the owner through the session's customer (see the first risk below), writes the StoredPaymentMethod mirror, and the account's card list shows it.

Flow B: returning donor at another charity

1. RecognisePassport session cookie on the Passport origin, or email plus code. The hosted checkout opens the Passport step in a popup on the Passport origin so the charity page never sees credentials.
2. SpokeIf this charity has no customer row for the account yet, create one (merchant, reference = account id, passportAccountId). Mirror the account's active tokens onto it.
3. SessionA normal checkout session for the charity's store, splits frozen as today, with customerId set and a flag marking it as a Passport session.
4. CardsThe payment-methods call now includes shopperReference for Passport sessions only, so Adyen returns the stored cards and the picker can render them.
5. ConfirmOne tap. Payment posted with paymentMethod.storedPaymentMethodId, shopperReference = account id, shopperInteraction Ecommerce, recurringProcessingModel CardOnFile. This is a cardholder-initiated payment on a stored credential. The issuer may challenge; the existing 3DS handling completes it. We do not claim a merchant-initiated exemption, because the donor is present.
6. AfterTransaction, splits, merchant webhook and merchant records exactly as today. Plus: a receipt email to the donor and the payment in their Passport history.

Flow C: remove a card or leave

1. Remove cardAdyen DELETE /storedPaymentMethods/{id} under the account's shopper reference, then every mirror set to DISABLED. Any subscription pinned to that card follows the existing needs-action path, so the Passport app warns the donor which charities' regular gifts will stop before confirming.
2. Delete accountAll tokens revoked at Adyen, credentials and sessions destroyed, email and name cleared from the account, customer rows unlinked. Merchant transaction records are retained as they must be; they no longer resolve to a person through Passport.

Decisions to confirm

Each has a recommendation. Confirming the page as it stands confirms all eight.

Phases

Change inventory by repository

Risks and the things that will bite

• Issuer challenges in a popup. A cardholder-initiated payment on a stored card can trigger 3DS. The popup must host the challenge or hand back to the page; the checkout's existing redirect helper covers the full-page case and needs the popup case added.
• Token processing model. Existing tokens are minted with recurringProcessingModel Subscription; Passport tokens with CardOnFile. Adyen accepts either for a later cardholder-initiated charge. Verify on TEST in phase 0 rather than assume.
• The payment-methods change is global. Sending a shopper reference changes what Adyen returns. Gate it to sessions that carry a Passport account so no merchant flow changes.
• Migrations are manual per environment and the schema is mirrored across four repositories. One migration, applied by hand before promotion, mirrored the same day.
• Next 15 nonce CSP. Every page in the Passport app renders per request or its scripts are blocked. Fonts self-hosted, because Google Fonts broke two production builds on the portal.
• Email delivery is the sign-in path. One-time codes ride the SMTP pipeline. The platform audit found bounce feedback unconsumed; Passport makes that a sign-in failure rather than a nuisance. Passkeys reduce the dependence after first sign-in.
• Enumeration. Sign-in by email must answer identically for known and unknown addresses, and sit behind the credential rate limiter from the first commit.
• Removing a card a charity relies on. A regular gift pinned to that card goes to needs-action and the charity's dunning email fires. The Passport app names the affected charities before the donor confirms.
• Deletion versus retention. Deleting a Passport account must not delete merchant transaction records. Unlink and anonymise; keep the money trail.

Once confirmed: the first week

In this order, each as its own change, so the risky one is reviewed alone.

1. Worker token-owner resolutionResolve through the checkout session or transaction's customer; fall back to the shopper reference as a customer id for legacy paths. Unit test for both. Promoted on its own.
2. Migration and modelsPassportAccount, PassportCredential, Customer.passportAccountId. Mirrored to the three sibling schemas. Applied by hand on dev.
3. Payments branchPassport sessions send the account id as shopper reference; cardholder-initiated mode on a stored token; payment-methods call includes the shopper reference for Passport sessions only.
4. Adyen recurring serviceList and delete stored payment methods, with request logging like every other Adyen call.
5. Passport auth and read APIEmail code start and verify, PASSPORT scope, me and cards endpoints, rate limits.
6. The spike scriptRegister at SimplyDonate, pay a second dev merchant with the saved card, assert both transactions, both splits, one Adyen token. This is the phase 1 acceptance test, run early.