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

Scope

This ADR covers:

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:

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:

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:

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

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

Negative / Trade-offs

Neutral


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.

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

  1. Input: dispatching RemoveCardCredentialCommand to end a lost phone’s device credential. Decision 7: it ends a device credential “without touching the card”. Decision 9: every mutating command’s Target is ("Card", CardId), so it acts on the card.
  2. Input: IssueCardCommand names “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:


Notes