This is the decision record as it was written, grilled and shipped. It’s copied from our repository unedited, apart from customer, partner and bank names, which read [redacted]. It was written for the people and agents building the product, so expect internal shorthand, and the mistakes are left in.
ADR-835: Cards and Authorisation: the card aggregate and its credentials
Status: Shipped — 2026-10-01
Outcome
A card is now its own aggregate with a configured card type: issue, activate, suspend, reinstate, report lost, reissue and close, controls with a travel window and a funding rule, device wallets with credential removal and reveal, all mirrored to the processor; a card viewer and a Cards panel show it. Landed as designed in six bites on Wolverine 6.44; new decline reasons map to ISO 8583 codes 14, 58 and 30.
Context
The Problem
ADR-820 shipped the seam to the issuer processor: three inbound doors, the receipts, a
Paymentology adapter, a simulator and the clearing batch. Nothing on our side of that seam
yet knows what a card is. A processor can ask us to authorise a token, and the decider seam
answers IssuerNotReady, because no record joins a token to a customer, a status, a set of
controls or an account the money would come from.
The cards proposal (docs/business/proposals/cards-capabilities.html, §4.3) and the card
model page (docs/business/models/card.md) decide the shape: the card is an aggregate of its
own, under the counterparty (ADR-314 D3). It is not a property of an account and not an
account. Before the oracle can decide anything it needs the card: who owns it, which
credentials it carries, whether it is active, what its controls say, and the ordered list of
accounts it draws on. That is this ADR.
What Already Exists
LedgerTM.Contracts/Cards(ADR-820):CardCredential(token reference, BIN, last four, expiry, kind),CardControls,CardStatus,CardCredentialKind,CardReissueKind,CardTokenReference,ICardProcessor(create, reissue, set status, set controls, order plastic, close),ICardTokenProvisioningDecider(the seam the provisioning door calls; no implementation registers today, so every wallet request is declined).LedgerTM.Cards(ADR-820): the processor facet, the doors, the receipts, the simulator withSimulateCardCreationCommand, which already returns a credential and never a card number.NoPrimaryAccountNumberTestsandCardVocabularyTests(ADR-820): a type on the cards surface with a PAN-shaped member fails the build; every card type carries the wordCard.- Account roles (ADR-327): who owns and who services an account, read through
IAccountOwningPartiesReaderandIHeldAccountsReader. - Vocabulary rows with strongly typed ids (ADR-422): a settings row other state refers to
declares an
Idderived from its key. - Four-eyes reviewability (ADR-780 D6, D7): an aggregate a checker can read registers an
IApproverViewReaderand a holder. - The client channel’s closed list of operations (ADR-695 D9), which this ADR does not extend.
Scope
This ADR covers:
- The
Cardaggregate: identity, owner, named cardholder, card type, billing currency, status, credentials, controls and funding rule. - The card type vocabulary, per tenant, in settings.
- The lifecycle verbs and their mirror to the processor.
- The funding rule and its two invariants (owner holds every account; every account is in the billing currency).
- The provisioning decider: a device wallet becomes a second credential on the same card.
- The read side the oracle and the UI need: the token index, the card list, the card detail.
- One card viewer and a cards panel on the counterparty viewer, with their guide articles.
- A sample card on the simulation tenant so the demo has one.
Out of scope: the authorisation decision, the hold and the per-account holds projection (the oracle ADR); the current account and the overdraft facility (the current account ADR); card fees of any kind, renewal at day-end and the revolving product (the card products ADRs); the client channel operations for cardholders and corporate administrators (the spend-controls ADR); disputes; velocity controls beyond the per-transaction ceiling ADR-820 already carries.
Decisions
1. The card is an aggregate under the counterparty, with its own id
Card is an EventSourcedAggregate with a generated CardId and a typed Owner
(CounterpartyId) field: many cards per counterparty, so attachment is by own id plus a field
holding the container’s id (ADR-314 D4). The account never learns a card exists; the card
holds the list of accounts it may draw on.
The owner is the counterparty whose accounts fund the card. A named cardholder is the
person the card is embossed for: on a personal card it is the owner, on a corporate card it is
an employee named on the card and never its owner (proposal §3.3). The aggregate records the
cardholder as an embossed name and an optional CounterpartyId, so a corporate’s employee who
is also a customer can be joined later without a second concept.
A card also carries a display name (“Groceries card”), the label its holder knows it by,
set at issue and changed by RenameCardCommand. It is never embossed and never sent to the
processor.
Why not a property of the account. The card has a lifecycle of its own (ordered, active, suspended, lost, reissued, closed) and credentials of its own, and one card draws on several accounts. ADR-314’s subject test says state that gains its own lifecycle leaves the container.
2. Card types are a vocabulary row, and product behaviour lives on the type
CardTypesSettings holds one CardType row per kind of card the tenant sells. The row’s
Id is CardTypeId, slug-derived from its key (ADR-422, VocabularyKey.Pattern), and a card
stores the id. The row carries what varies by product:
- the credential kinds the type may carry (plastic, virtual, device token); a first credential is plastic or virtual;
- the default controls a new card starts with;
- the funding shape:
OrderedList(a debit card walks its owner’s accounts) orSingleAccount(a credit card’s list has exactly one entry, its revolving account); - the account types a funding rule may name, as typed ids;
- whether the cardholder may differ from the owner (a corporate card) — a rule, not a product name;
- how a first device-wallet request is answered:
ApproveorStepUp; - the credential life in years, sent to the processor at creation and read by the renewal step a later ADR adds;
- an optional cap on active cards per owner of this type (a second plastic debit card is refused; a virtual beside a plastic is not, when the cap says two).
Nothing on Card is named for a product. A debit card and a credit card are two rows. A row
that cards still name cannot be removed or re-keyed (CARD_TYPE_IN_USE); its key is its id.
3. Issuing a card calls the processor first, then records what it answered
IssueCardCommand names the owner, the cardholder, the card type, the billing currency, the
first credential’s kind (plastic or virtual; a device token is never a first credential, it
is added by Decision 7), the controls and the funding rule. The handler validates the rule
(Decision 5), calls ICardProcessor.CreateCardAsync, and only then lets the aggregate Issue,
which emits CardIssued carrying the credential the processor returned. A processor failure
refuses the command and no card exists.
The command carries the CardId it will create, and the adapter passes it to the processor as
the idempotency reference where the processor supports one, so a retry after a processor
success and before our commit does not mint a second card at the processor. Where the
processor supports none, the retry’s duplicate is the processor’s and is visible in its
portal; this ADR records the gap rather than hiding it.
The embossed name is one to 26 characters of A–Z, spaces, hyphens, apostrophes and full stops after upper-casing, the scheme’s embossing line. A display name or a reason that carries thirteen or more digits, separators ignored, is refused: free text is the one place a card number could still enter our records. A re-sent issue under an id that already has a stream is refused before the processor is called, and the simulator answers a repeated reference with the card it already made.
A virtual card is active on issue. A plastic card is issued Ordered and activated by
the bank or the cardholder on receipt (ActivateCardCommand); OrderPlasticAsync is called at
issue for a plastic first credential.
4. The ledger’s status is the truth; the processor is mirrored after commit
The lifecycle verbs are Activate, Suspend, Reinstate, ReportLostOrStolen, Reissue
and Close, each a command on the aggregate with a status guard. The guards and the operations
menu (Decision 12) are one table, proven equal by a unit test:
| Verb | Offered and accepted at |
|---|---|
| Activate | Ordered |
| Suspend | Active |
| Reinstate | Suspended |
| Report lost or stolen | Ordered (plastic lost in the post), Active, Suspended |
| Reissue with a new number | Active, Suspended, LostOrStolen |
| Reissue with the same number | Active |
| Close | every status but Closed |
| Rename, set controls, set travel window, set funding rule | Ordered, Active, Suspended |
| Remove a device credential | Active, Suspended |
| Reveal | Ordered, Active |
Anything else is refused naming the status, before the processor is called, so a refused reissue mints nothing. Each verb emits its event.
Every such handler returns its events and an outgoing MirrorCardToProcessorCommand, whose
handler calls SetStatusAsync (or CloseAsync) on the processor after the event commits,
through Wolverine’s outbox, so the processor’s stand-in agrees with the ledger when we cannot answer. The handler
tells the processor the card’s current status at handling time, not the event’s, so two
messages delivered out of order converge on the truth. A mirror failure retries and
dead-letters; it never rolls the ledger back. The oracle reads our status, never the
processor’s.
Expiry is a credential’s state, not the card’s. A credential whose expiry month has passed
is expired; the oracle refuses it. The card stays Active so a renewal can replace the
credential without a lifecycle act; a card whose every credential has expired and is not
renewed is closed by the bank.
Reissue calls the processor first, as issue does, and with NewNumber closes the old
credential and records the new one from the processor’s answer (from Active or
LostOrStolen, a plastic card is Ordered again and its plastic is ordered and a virtual card
is Active; a Suspended card stays Suspended, because a fraud review is not ended by a new
number); with SameNumberNewExpiry it
keeps the token, records the new expiry, orders plastic for a plastic card and the card stays
Active. A LostOrStolen card accepts only NewNumber.
5. The funding rule is an ordered list the owner holds, all in the billing currency
SetCardFundingRuleCommand carries an ordered list of one or more AccountIds. The aggregate
holds it as given; the handler refuses the command when:
- any account is not held by the owner on the day, read through
IHeldAccountsReader(ADR-327’s roles decide what “held” means); - any account’s currency, read through
IAccountReferenceProvider, is not the card’s billing currency; - any account’s type is not on the card type’s list of fundable types;
- the card type’s shape is
SingleAccountand the list has more than one entry.
The rule is a plain list. No expression, no split: an expression is unbounded inside an authorisation timeout and unreadable to a clerk explaining a decline; a split produces two postings for one receipt (proposal, grill of 29 September 2026). An overdraft is never a list entry; it is the facility on the account, which the oracle reads as part of that account’s available.
The oracle ADR walks this list. It is stored on the card so that walk is a read of one document and no cross-feature call.
6. Controls are set on the card and told to the processor; they only ever narrow
SetCardControlsCommand replaces the card’s CardControls. ADR-820’s shape changes at the
grill (2026-10-01), read off a private-banking card in use: five switches — online, in-store,
in-store abroad, ATM, contactless — where ADR-820 had four with one AbroadAllowed; and two
nullable amounts in the billing currency, DailyCeiling and MonthlyCeiling, because a demo
clerk looks for a daily limit first. Declaring the shape here means the oracle reads it without
a later ADR reshaping a shipped type. AbroadAllowed becomes InStoreAbroadAllowed: the one
non-additive change this ADR makes, two days after the type shipped, with no tenant data
holding it beyond the simulator’s records.
A ceiling is a non-negative amount; the daily ceiling is at least the per-transaction one and the monthly at least the daily. The day is the tenant’s trading date and the month is that date’s calendar month; the oracle sums against both.
A travel window. SetCardTravelWindowCommand records, or clears, a dated allowance: from,
to (today or later), and at least one country (IsoCountryCode, ADR-386) the holder will visit.
The processor is not told it in this ADR, so its stand-in may decline a traveller we would allow. Inside the window a card-present
transaction in a listed country is allowed even when in-store abroad is off. It is one
CardTravelWindow per card, replaced whole; the oracle reads it beside the switches. The bank
sets it now; the cardholder sets it when the portal verb arrives.
A card ceiling is the first of three caps a hold must pass, and it only ever narrows:
| Cap | What it bounds | Where the oracle reads it |
|---|---|---|
| the card’s ceilings | this card, per transaction, day and month | on the card, before the funding walk |
| the account’s facility | how far one account may be drawn | inside the account’s available balance |
the customer’s credit limit (LedgerTM.Limits) |
the customer’s exposure across accounts | through the account’s available, as the limit integration per account type does today |
A ceiling can never let a hold through that the account’s available would refuse, and the
reason code names which cap said no. The account-side mechanics are the oracle ADR’s. The mirror handler calls SetControlsAsync after
commit so the processor’s stand-in can refuse in our absence. The oracle evaluates controls
from our record, never from the processor’s.
7. A device wallet is a second credential on the same card
CardTokenProvisioningDecider implements ADR-820’s ICardTokenProvisioningDecider. It
resolves the request’s token reference to a card through the token index and answers:
Declinewhen no card holds the token, or the card is notActive, or its type does not allow device tokens;Declinewhen the request names no device token: a credential always has its token, so removal and the token index never meet a tokenless one;StepUpwhen the type says a first device steps up and no provisioning receipt on this tenant’s trading date, after the token’s last removal from the card, already answeredStepUpfor that device token (the decider reads receipts, never writes them);Approveotherwise.
Each answer carries its reason (CardDeclineReason, which gains UnknownToken,
DeviceTokensNotAllowed and DeviceTokenMissing): ADR-820’s seam returned the bare decision
and the receipt could not say why, so the seam changes two days after it shipped, with two
readers. Verifying the holder during step-up (the one-time code) is the portal ADR’s; until it
ships, a step-up is passed by the wallet asking again the same day with the token it will mint.
The decider writes and publishes nothing (ADR-820 D5). The door’s handler, once it has
committed an Approved receipt, cascades AddCardDeviceCredentialCommand (system-internal),
and the card records CardDeviceCredentialAdded with the device token, the wallet provider and
the device description. An answer that misses the budget therefore records no credential. The
scheme’s token service names the device token it is about to mint in the provisioning request
(EMVCo payment tokenisation), so ADR-820’s CardTokenProvisioningRequest gains a nullable
DeviceTokenReference and the mapper fills it; the token index binds at approval.
RemoveCardCredentialCommand ends a device credential (a lost phone) with
CardCredentialRemoved on the card’s stream and the mirror closes the token at the processor;
the card’s status does not change, and a removed token that provisions again is a new
credential. A NewNumber reissue closes the device tokens with the old number; the wallets
provision again. The door cascades the credential command only when the token resolves to a
card.
8. Card details and PIN are revealed by the processor’s hosted view, never by us
A cardholder expects to see their full number, CVV and PIN; the platform never holds any of
them (ADR-820 D9). ICardProcessor gains RequestRevealAsync(token, kind), which asks the
processor for a short-lived reveal session: the address of a view the processor hosts and
when it expires. RevealCardCommand (key cards.reveal-card) answers that session for the
viewer to embed, for CardDetails or Pin, and records CardDetailsRevealed (kind and date,
never the address) on the card’s stream: PCI DSS v4.0 10.2.1.1 wants every access to
cardholder data logged, and a read leaves no trail. It is INotFourEyesGated because a session
expires in minutes. The number crosses from the processor to the holder’s screen and never
through us; the request record redacts the address at capture, as it does a card number.
No template grants cards.reveal-card to a bank role: it exists for the cardholder’s portal
verb, which a later ADR adds, and a bank that wants a clerk to reveal grants it deliberately.
The simulator’s hosted view shows placeholders and no digits, so NoPrimaryAccountNumberTests
stays the whole story.
9. The read side: a token index and a card summary, both inline
CardByToken: one document per credential token,CardTokenReference → CardId, inline, so the oracle resolves a token in one lookup consistent with every credential written. Read throughICardByTokenReaderin Contracts, for the oracle ADR.CardSummary: one document per card — owner, cardholder, type, billing currency, status, the credentials askind · BIN …… last four · expiry, controls, funding rule. Inline. The card list (ListCardsQuery, by owner) and the card detail (GetCardQuery) read it.
Nothing in either document holds more than the credential’s BIN and last four
(NoPrimaryAccountNumberTests covers both).
10. Permissions, feature and four-eyes
Every command here gets a cards.* key, bound to cards.issuing in the feature catalogue:
issue-card, activate-card, suspend-card, reinstate-card, report-card-lost-or-stolen,
reissue-card, close-card, rename-card, set-card-controls, set-card-travel-window,
set-card-funding-rule, remove-card-credential, amend-card-types, view-card-types,
view-cards, view-card, reveal-card; and two system-internal keys, add-card-device-credential and mirror-card-to-processor. The
Simulate* keys stay ADR-820’s.
Card is reviewable: it registers a CardApproverViewReader (status, cardholder, type,
credentials masked, controls, funding rule as of the day) and is a SelfHoldingAggregate
(ADR-780 D6, D7). Every mutating command’s Target is ("Card", CardId); IssueCard’s target
is the owner ("Counterparty", the owner’s id), because the card does not exist yet; a checker
reads the pending command’s fields, since the processor is called only when the approved
command runs. SuspendCard and ReportCardLostOrStolen are INotFourEyesGated: they are
protective, and delay is the risk. Every other verb is eligible and the tenant’s rules decide.
11. The UI: a cards panel on the counterparty, a card viewer
The counterparty viewer gains a Cards panel listing the owner’s cards with an Issue card
operation. A card viewer at route:/cards/{id} opens on Details (display name, credentials masked, status,
type, billing currency, cardholder, a Reveal action where the key is held) with Controls,
Travel and Funding panels and the lifecycle
operations. Card types are a settings page under reference data. Three guide articles ship
with the bites that add them (ADR-407).
12. The card’s verbs are linked operations; the card hosts no interpreted ones yet
Every verb a person performs on a record is an operation (ADR-744 D4), and a verb that is
platform code is a linked entry in DispatchedOperations (ADR-744 D5): a name, a label,
a group, its own catalogued permission key, a feature key and the statuses it is offered at.
DispatchedOperations.ForCard declares Activate (Ordered), Suspend (Active), Reinstate
(Suspended), Report lost or stolen (Active, Suspended), Reissue (Active,
LostOrStolen), Close (every status but Closed), Set controls and Set funding rule
(Ordered, Active, Suspended), Rename and Set travel window (Ordered, Active,
Suspended), each under cards.issuing. The card viewer’s operations
menu and its availability come from that registry, so a clerk sees the same shape on a card as
on a counterparty.
The card hosts no interpreted operations and no property bag in this ADR. ADR-757 D4
hosts the engine on every container aggregate; the card is a concept aggregate whose subject
matter is typed (credentials, controls, funding rule), and nothing a tenant configures on a
card is a free property yet. When one appears, CardType implements IOperationHost and the
engine is composed, as Accounts composes it; nothing here is built to make that harder.
13. The simulation tenant seeds one card
SeedSampleCards (simulation phase, beside ADR-820’s processor seed) issues one active virtual
debit card for the demo customer through the simulator, funded from their call deposit, so the
oracle ADR’s demo starts with a card that exists. The retail package carries no current account
yet (the current account ADR adds it), so the fundable types on the seeded debit card type
name CallDeposit until then.
Contracts
Ids — CardId (generated), CardTypeId (slug-derived from the type row’s key).
Values — CardFundingRule (ordered list of AccountId), CardholderReference (embossed
name, optional CounterpartyId), CardFundingShape (OrderedList, SingleAccount),
DeviceProvisioningRule (Approve, StepUp), CardTravelWindow (from, to, countries),
CardRevealKind (CardDetails, Pin), CardRevealSession (hosted view address, expiry).
Settings — CardTypesSettings with rows CardType (key, label, credential kinds, default
controls, funding shape, fundable account types, cardholder may differ from owner, device
provisioning rule, credential life in years, optional cap on active cards per owner).
Commands — IssueCardCommand, ActivateCardCommand, SuspendCardCommand,
ReinstateCardCommand, ReportCardLostOrStolenCommand, ReissueCardCommand,
CloseCardCommand, RenameCardCommand, SetCardControlsCommand, SetCardTravelWindowCommand,
SetCardFundingRuleCommand, RemoveCardCredentialCommand — each ICommand with Target ("Card", id) except IssueCard,
whose target is the owner. AmendCardTypesCommand — ISettingsCommand<CardTypesSettings>.
AddCardDeviceCredentialCommand — ISystemCommand, cascaded by the provisioning door once its
Approved receipt commits. MirrorCardToProcessorCommand — ISystemCommand, cascaded by every
status, controls, reissue and removal handler.
Events — CardIssued, CardActivated, CardSuspended, CardReinstated,
CardReportedLostOrStolen, CardReissued, CardClosed, CardRenamed, CardControlsSet,
CardTravelWindowSet, CardFundingRuleSet, CardDeviceCredentialAdded,
CardCredentialRemoved, CardDetailsRevealed — each dated with the trading date, in
LedgerTM.Cards (the oracle is the same project).
Queries — ListCardsQuery (by owner, answers CardSummary rows), GetCardQuery (one
CardSummary), GetCardTypesQuery; RevealCardCommand (key cards.reveal-card) answers a
CardRevealSession and is a command (Decision 8). GET /api/cards/{id}/operations answers
the engine’s verdicts over the card’s linked operations.
Read documents — CardSummary, CardByToken.
Interfaces — ICardByTokenReader (Contracts: token reference → CardId, for the oracle).
CardTokenProvisioningDecider implements ADR-820’s ICardTokenProvisioningDecider.
DispatchedOperations.ForCard (in LedgerTM.Operations) declares the card’s linked verbs.
Consumed from LedgerTM.Contracts — IHeldAccountsReader, IAccountReferenceProvider, AccountTypeId, CurrencyId,
CounterpartyId.
Consumed from LedgerTM.Cards — ICardProcessor, ICardTokenProvisioningDecider, CardCredential, CardControls, CardStatus, CardReissueKind, CardTokenReference. Each lived in Contracts when this ADR shipped, and moved to its only reader on 2026-10-21 (ADR-755 ruling).
Consumed from LedgerTM.Infrastructure.Contracts — IApproverViewReader,
SelfHoldingAggregate, ISettingsCommand<T>, ICapabilityProvider.
Changed — CardControls: AbroadAllowed becomes InStoreAbroadAllowed, InStoreAllowed
added, DailyCeiling and MonthlyCeiling added (nullable); CardTokenProvisioningRequest
gains DeviceTokenReference (nullable); ICardProcessor gains RequestRevealAsync;
CardCreationRequest gains Reference (the card id, the processor’s idempotency key) and
CredentialLifeYears; ICardTokenProvisioningDecider returns CardTokenProvisioningAnswer
(decision and reason) and CardDeclineReason gains three members. All ADR-820’s types; the
first carries one rename, the last changes a seam with two readers.
Removed — none.
Prior art
| Declared | Search returned | Verdict |
|---|---|---|
Card |
nothing on the contract surface; the proposal’s “card aggregate” (§4.3) and the model page name it | genuinely new — the proposal’s term, under the counterparty |
CardId |
CardAuthorisationId, CardTokenReference (ADR-820): a processor’s references |
genuinely new — our own identity for the card; the token is the processor’s |
CardTypeId, CardType, CardTypesSettings |
CounterpartyTypesSettings, AccountTypesSettings, ADR-422’s vocabulary rows |
reuse the pattern — a per-tenant vocabulary row with a slug-derived id |
CardFundingRule, CardFundingShape |
nothing; the proposal §4.2 “funding rule: an ordered list” | genuinely new — the proposal’s term |
SetCardFundingRuleCommand, CardFundingRuleSet |
AmendCardTypesCommand and every Amend*Settings command (verb/event pair on an aggregate) |
genuinely new — the card’s own verb and event setting the rule from §4.2; not a settings mutation |
CardholderReference |
CounterpartyReference (ADR-040, a display type) |
genuinely new — an embossed name plus an optional counterparty; not a display projection |
DeviceProvisioningRule |
CardTokenProvisioningDecision (ADR-820: the answer) |
genuinely new — the type’s rule for answering, not the answer |
IssueCardCommand … RemoveCardCredentialCommand |
SimulateCardCreationCommand (ADR-820: the simulator’s test-only creation) |
genuinely new — the bank’s verbs on its own record; the simulator stays as the processor’s side |
AmendCardTypesCommand |
AmendCardProcessorCommand (ADR-820) and every Amend*Settings command |
reuse the pattern — ISettingsCommand<T> |
AddCardDeviceCredentialCommand |
DecideCardTokenProvisioningCommand (ADR-820: the door) |
genuinely new — the door decides, this records; the decider must not write into the door’s unit of work |
CardIssued … CardCredentialRemoved |
ADR-820 ships no events | genuinely new — the first card events; frozen once shipped |
ReissueCardCommand, CardReissued |
CardReissueKind (ADR-820: the kind the processor is asked for) |
genuinely new — the bank’s verb and its event; the kind travels inside both |
SetCardControlsCommand, CardControlsSet |
CardControls (ADR-820: the value the processor is told) |
genuinely new — the verb and event that set the value; the value is reused unchanged |
CardControls.DailyCeiling, CardControls.MonthlyCeiling, CardControls.InStoreAllowed, CardControls.InStoreAbroadAllowed |
CardControls.PerTransactionCeiling, CardControls.AbroadAllowed (ADR-820) |
extend — two more ceilings and a split of abroad into in-store and in-store abroad, on the same value |
CardTravelWindow, SetCardTravelWindowCommand, CardTravelWindowSet |
IsoCountryCode (ADR-386) for the countries; CardControls is undated |
genuinely new — a dated allowance beside the switches, over the existing country code |
RenameCardCommand, CardRenamed |
UpdateCounterparty (a property change) |
genuinely new — a card’s own label, never embossed |
CardCreationRequest.Reference, CardCreationRequest.CredentialLifeYears, CardProcessorException |
CardCreationRequest (ADR-820) |
extend — the idempotency reference and the life the type decides; the processor’s refusal as a typed exception |
CardTokenProvisioningAnswer, CardDeclineReason.UnknownToken, DeviceTokensNotAllowed, DeviceTokenMissing |
ICardTokenProvisioningDecider, CardDeclineReason (ADR-820) |
extend — the seam answers with its reason |
CardDetailsRevealed |
CardAuthorisationReceipt (ADR-820: a decision’s record) |
genuinely new — the access trail PCI DSS 10.2.1.1 asks for |
ICardProcessor.RequestRevealAsync, CardRevealKind, CardRevealSession, RevealCardCommand |
ICardProcessor (ADR-820), SignedFileLinks (a short-lived address the platform mints) |
extend — one more processor verb; the session is the processor’s address, not ours |
CardTokenProvisioningRequest.DeviceTokenReference |
CardTokenProvisioningRequest.Token (ADR-820: the card’s token) |
extend — the device token’s own reference beside the card’s |
CardDeviceCredentialAdded |
CardCredential, CardCredentialKind.DeviceToken (ADR-820) |
genuinely new — the event recording a credential of the existing kind on the card |
ListCardsQuery, GetCardQuery, GetCardTypesQuery |
ListCardProcessorReceiptsQuery, GetCardProcessorQuery (ADR-820) |
reuse the pattern — IQuery<T> with a view |
CardSummary, CardByToken |
CardAuthorisationReceipt (ADR-820: keyed by the processor’s reference) |
genuinely new — the card’s own read models; the receipt is a decision’s record |
ICardByTokenReader |
IHeldAccountsReader, IAccountOwningPartiesReader (Contracts readers) |
reuse the pattern — a Contracts reader for the one question the oracle asks |
CardTokenProvisioningDecider |
ICardTokenProvisioningDecider (ADR-820 seam, no implementation) |
implements — the seam’s first implementation |
CardApproverViewReader |
SettingsApproverViewReader, every *ApproverViewReader |
reuse the pattern — ADR-780 D6 |
DispatchedOperations.ForCard |
DispatchedOperations.ForCounterparty and its siblings (ADR-744 D5) |
extend — one more host’s linked entries in the one registry |
MirrorCardToProcessorCommand |
the feed-delivery consumers (ADR-766), CardProcessorClient (ADR-820), ADR-820’s clearing steps cascading a system command |
reuse the pattern — a cascaded system command calling the resolved processor after commit |
ICardProcessor, ICardTokenProvisioningDecider, CardCredential, CardControls, CardStatus, CardReissueKind, CardTokenReference |
ADR-820 | reuse unchanged |
IHeldAccountsReader, IAccountReferenceProvider, AccountTypeId, CurrencyId, CounterpartyId, AccountId |
Contracts | reuse unchanged |
IApproverViewReader, SelfHoldingAggregate, ISettingsCommand<T>, ICapabilityProvider |
Infrastructure.Contracts | reuse unchanged |
Relies on
| Symbol | What it does today | What this ADR assumes |
|---|---|---|
ICardProcessor |
The outbound seam, resolved per tenant by the facet’s kind (ADR-820 D3) | Issue, reissue, status, controls and close reach the tenant’s processor |
ICardTokenProvisioningDecider |
Called by the provisioning door; none registered means Decline with IssuerNotReady |
This ADR registers the one implementation |
IHeldAccountsReader |
The accounts a counterparty holds on a day (ADR-327 roles) | A funding rule may name only those |
IAccountReferenceProvider |
An account’s number, type, owner, operating entity and currency | The billing-currency and fundable-type checks read it |
StrongId.SlugFor |
Normalises a vocabulary key into a slug-derived id (ADR-422) | CardTypeId derives from the row’s key |
IApproverViewReader |
What a checker reads of an aggregate under four-eyes (ADR-780 D6) | Card registers one |
SelfHoldingAggregate |
An aggregate that is its own change-set holder (ADR-780 D7) | Card is one |
SettingsCommandMiddleware |
Loads and saves a settings root around a handler | AmendCardTypesCommand |
FeatureSettings |
Absent key means off (ADR-363) | Every key here binds to cards.issuing |
The build test NoPrimaryAccountNumberTests (ADR-820 D9) walks every type this ADR adds.
| CardDispatchedOperations | The card’s linked operations, read by its viewer’s operations menu (ADR-744 D5); each feature now owns its own list | Was DispatchedOperations.ForCard |
Worked example
Fixture: the za-retail tenant (package retail-bank), simulation on, cards.issuing
licensed, processor kind Simulator (ADR-820’s seed). The demo customer holds a CallDeposit
with 4,200.00 ZAR. Card type debit (ordered list, fundable CallDeposit, plastic and virtual
and device tokens, first device steps up, three-year credentials). Dates are trading dates.
| Row | Before | After |
|---|---|---|
| Issue a virtual debit card to the customer, funding rule [call deposit], default controls | no card | CardIssued: status Active, credential Virtual · 400000 …… 0001 · 2029-10, owner = cardholder, billing ZAR; CardByToken maps the token to the card |
| Issue a plastic card to the same customer | one card | a second card, status Ordered; the processor was asked to order plastic |
| Activate the plastic card | Ordered |
CardActivated; the processor is told Active after commit |
| Set controls: online off, in-store abroad off, per-transaction ceiling 2,000.00, daily 5,000.00 | default controls | CardControlsSet; the processor is told after commit |
| Set a travel window 10–24 October 2026, countries GB and FR | none | CardTravelWindowSet; the summary shows it |
| Rename the virtual card “Groceries card” | display name = type label | CardRenamed; the processor is not told |
Request a reveal of card details by a person holding cards.reveal-card |
— | a hosted-view address and an expiry; CardDetailsRevealed on the card’s stream; no digit of the number anywhere in our records |
| Issue a second plastic debit card to the customer, the type capping plastic at one | one plastic card | refused naming the cap |
| Set the funding rule to [call deposit, a savings account the customer does not hold] | [call deposit] | refused, naming the account the owner does not hold; the rule is unchanged |
| Set the funding rule to [a USD account the customer holds] | [call deposit] | refused, naming the currency; the rule is unchanged |
| A wallet asks to provision the virtual card to a first device | no device credential | StepUp; the receipt says so; no credential yet |
| The same wallet asks again the same day, naming its device token | no device credential | Approve; CardDeviceCredentialAdded (Apple Pay, iPhone 16, device token); the device token resolves to the card |
| A wallet asks with no device token | — | Decline, DeviceTokenMissing |
| Suspend, then reinstate | Active |
Suspended then Active, two mirrors to the processor |
| Report the plastic card lost | Active |
LostOrStolen; the processor is told; the card cannot authorise |
| Reissue it with a new number | LostOrStolen |
CardReissued: new credential 400000 …… 0002, old credential closed, status Ordered |
| Close the virtual card | Active |
CardClosed; the processor is told; every later command is refused |
A card type gains a key Travel Card |
— | refused: a key must be kebab-case (travel-card), per ADR-422 |
| Checker opens the issue for approval | — | reads the pending command: owner, cardholder, type, display name, controls, funding rule; the credential does not exist until the approved command runs |
Model
Generated from docs/model/model.json (ADR-773 D8): the shape the model knows today, <<new>> for what
## Contracts declares and the model does not know, relies-on for ## Relies on. Regenerate with
python3 scripts/model/adr_model.py ADR-NNN --write; frozen at Shipped.
classDiagram
class FeatureSettings {
<<settings, relies-on>>
}
class AbroadAllowed {
<<new>>
}
class Approve {
<<new>>
}
class Approved {
<<new>>
}
class CardDetails {
<<new>>
}
class CredentialLifeYears {
<<new>>
}
class DailyCeiling {
<<new>>
}
class DeviceTokenReference {
<<new>>
}
class InStoreAbroadAllowed {
<<new>>
}
class InStoreAllowed {
<<new>>
}
class IssueCard {
<<new>>
}
class MonthlyCeiling {
<<new>>
}
class OrderedList {
<<new>>
}
class Pin {
<<new>>
}
class Reference {
<<new>>
}
class RequestRevealAsync {
<<new>>
}
class SingleAccount {
<<new>>
}
class StepUp {
<<new>>
}
class CardDispatchedOperations {
<<relies-on>>
}
class IAccountReferenceProvider {
<<relies-on>>
}
class IApproverViewReader {
<<relies-on>>
}
class ICardProcessor {
<<relies-on>>
}
class ICardTokenProvisioningDecider {
<<relies-on>>
}
class IHeldAccountsReader {
<<relies-on>>
}
class SelfHoldingAggregate {
<<relies-on>>
}
class SettingsCommandMiddleware {
<<relies-on>>
}
class StrongId {
<<relies-on>>
}
Consequences
Positive
- The oracle ADR becomes a read of one document and a decision; everything it needs is on the card.
- A device wallet, a virtual card and a plastic card are one concept with three credential kinds, which is what the proposal sells against vendors who treat them as three products.
- A card’s whole history, including the processor’s part, is on one stream a checker and an auditor can replay.
Negative / Trade-offs
- The processor is called inside the issue handler, before commit: a processor outage refuses issuance rather than queueing it. Queueing would mean a card record with no credential, which nothing downstream can use.
- The mirror is eventually consistent. Between commit and mirror the processor’s stand-in may answer differently from the ledger for a suspended card; the window is the outbox’s, seconds.
- Step-up is passed by the wallet asking again the same day; verifying the holder is the portal ADR’s, so until it ships a step-up is a delay, not a check.
- Two of ADR-820’s types change shape and one seam changes its return type, two days after they shipped; nothing stored holds them beyond simulation data.
- The travel window is ours alone until the processor adapter learns it; in stand-in the processor may decline a traveller the oracle would approve.
Neutral
- Card fees, renewal and the client-channel operations are deliberately later ADRs; this one is the record they all act on.
Implementation Plan (Bites)
Six bites, one land. Bites, acceptance criteria, scenarios, files touched and status live in ADR-835-plan.md.
Changed during the grill
Grilled 2026-10-01 with the operator, from the card model page.
- Controls gained daily and monthly ceilings (Decision 6;
CardControlschanged, additively). The draft carried ADR-820’s per-transaction ceiling only; a demo clerk looks for a daily limit first, and declaring it here spares a later ADR reshaping a shipped type. The operator chose it over leaving velocity to the spend-controls ADR, and asked whether it sits beside the customer’s credit limit and the account’s facility: it does, as the first of three caps, and the other two are the account’s and the customer’s, never the card’s. - The device token’s late binding closed (Decision 7;
CardTokenProvisioningRequestchanged, additively). The draft recorded the oracle’s “unknown device token” question as a gap; the scheme’s token service names the token in the provisioning request, so the index binds at approval and the late case is the exception. - The mirror tells the current status, not the event’s (Decision 4), so out-of-order delivery converges. The draft was silent on ordering.
- Expiry is a credential state, not a card status (Decision 4). The draft was silent on what an unrenewed credential does to the card.
- A card type may cap active cards per owner (Decision 2). The draft allowed any number.
- The embossed name is bounded to the scheme’s 26-character line (Decision 3).
- Read off a private-banking card in use (the operator’s own, 2026-10-01): a display name
(Decision 1); five switches instead of four,
AbroadAllowedsplit into in-store and in-store abroad (Decision 6, the one rename of a shipped member); a dated travel window with countries (Decision 6); and card-detail and PIN reveal through the processor’s hosted view (Decision 8,ICardProcessorextended). Pause and cancel are Suspend and Close, already there. - The verbs are linked operations (Decision 12), surfaced by
make adr-check’s model press naming ADR-757: the card hosts no interpreted operations yet. - Pressed and held: the card as an aggregate under the counterparty (Decision 1, against “a property of the account”); the processor called before commit (Decision 3, against queueing issuance); the plain-list funding rule (Decision 5, against an expression and a split); the exclusions of fees, renewal, the channel operations and velocity beyond ceilings.
Contradiction press: 2 pairs, resolved as — RemoveCardCredential is an event on the card’s
stream that leaves its status unchanged (Decision 7 reworded, Decision 9 stands); a first
credential is plastic or virtual and a device token is only ever added by provisioning
(Decisions 2 and 3 reworded).
Contradiction press: 2 pairs
- Input: dispatching
RemoveCardCredentialCommandto end a lost phone’s device credential. Decision 7: it ends a device credential “without touching the card”. Decision 9: every mutating command’sTargetis("Card", CardId), so it acts on the card.- Input:
IssueCardCommandnames “device token” as the first credential’s kind. Decisions 2 and 3: permitted, device token is a listed kind and the command accepts any first kind. Decision 7: a device token is always a second credential, added after a wallet asks.Pressed hardest and found no contradiction: the active-card cap against the worked example’s sequencing; the funding-rule refusals against the two worked-example rows; the lifecycle guards (Decision 4) against the per-status operation list (Decision 11).
Changed during the plan grill
Phase A (the test author’s question pass, 27 questions) and the plan grill (15 points), 2026-10-01, operator’s standing instruction to take positions:
- The provisioning seam answers with a reason (Decision 7;
ICardTokenProvisioningDeciderchanged). A bare enum left the receipt unable to say why. - A device credential always has its token (Decision 7): a request without one is declined, so no tokenless credential exists; the late-binding paragraph is gone.
- The door cascades the credential command after its
Approvedreceipt commits (Decision 7): a publish from inside the decider could outlive the budget. - Step-up matches on the device token within the trading date, and holder verification is the portal ADR’s (Decision 7).
- Reveal is a command with an event (Decision 8): a read left no PCI trail and could never be gated; the address is redacted from the request record.
- The mirror closes tokens (Decisions 4, 7): a reissued or removed credential stayed live at the processor’s stand-in; a reissue closes the device tokens with the old number.
- Events gain a trading date, a message identity and a home in
LedgerTM.Cards; the summary stores expiry, never an “expired” flag. - Typed references: fundable account types are
AccountTypeIds, countriesIsoCountryCodes. - Ceilings validated and dated (Decision 6): the day is the trading date, the month its calendar month.
- A type row in use cannot be removed or re-keyed (Decision 2).
- Suspend and Report lost or stolen are not four-eyes gated (Decision 10): protective acts.
- Handlers do their lookups, validators only format: a validator’s session is untenanted under a seed step (ADR-719), and the sample card is issued through the real command.
- Phase B (six authors): refusal statuses are the host’s (400 validator, 422 domain); the
status guards and the menu are one table with a parity test, and a plastic card lost in the
post can be reported at
Ordered; a re-sent issue is refused before the processor; free text refuses a card number; the travel window is not yet mirrored;IsoCountryCodegains a JSON converter; the door cascades only for a known card. - Three scenarios added for verbs no test dispatched (activate and close, removing a device credential, the operations menu) and the expired-credential scenario split into two.
cards.view-card-typesjoins Decision 10’s list: seventeen keys plus two system-internal.
Notes
- Depends on ADR-820 (Shipped). Nothing here waits on the oracle or the current account ADR; both consume this one.
- The oracle ADR takes
ICardByTokenReader,CardSummary’s status, controls and funding rule, and Decision 7’s device-token question. - The current account ADR adds
CurrentAccountto the retail package; the seeded debit card type’s fundable types gain it then, as a template edit plus a migration step for provisioned tenants. - Reseed: the card type rows and the sample card are seed data (
reseed: true). - Register: ISO/IEC 7812 and PCI DSS v4.0 rows exist from ADR-820; this ADR adds no row.