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-820: Card Connectivity — the processor contracts and the Paymentology simulator
Status: Shipped — 2026-09-30
The first ADR of the cards series seeded by Cards, Inside the Ledger (sections 7, 8 and 11). It builds the seam every later card ADR stands on, and nothing above it.
Outcome
A card processor now connects as a configured facet: authorisation, reversal and token-provisioning doors answer inside the budget from insert-once receipts, and a Paymentology adapter and simulator carry the outbound seam and the clearing-file import. Landed as designed across seven bites, plus a Worker that starts without a secret store and the card seam’s reachability reason relabelled (F-1577).
Context
The Problem
LedgerTM has no card of any kind. The proposal decides that it never will have a switch: the issuer processor owns real-time authorisation, the PAN vault, tokenisation, the scheme connections and card production, and LedgerTM is the system of record behind it. What LedgerTM needs is the seam to that processor, and it needs it before a card aggregate, an authorisation oracle or a card product can be designed, because those three compile against the names this seam declares and a contract name cannot be renamed once shipped.
Four things cross the seam, in two tempos. In real time, the processor asks whether to approve an authorisation and whether a card may be provisioned to a device wallet, and it tells us when a merchant reverses an authorisation. In request and reply, we tell the processor to create, reissue, block, control and close a card, and it hands back a credential. Daily, the processor delivers a clearing file, one line per cleared item, which is the fact the ledger posts from.
Nothing above the seam may learn the processor’s field names, and nothing on either side may carry a primary account number, because a system that stores, processes or transmits a PAN is in PCI DSS scope and a system holding a token reference, the BIN and the last four is not.
What Already Exists
- The platform half, designed and not yet built. ADR-821 (Proposed) owns the
InstitutionConnectionsettings row with its transport and client id, the OAuth2 client-credentials machine principal bound to one tenant and one connection, the connection identity frame, and theIExternallyAuthenticatedCommandmarker that keeps a machine’s command out of four-eyes. A card processor is an institution we exchange with; this ADR attaches a facet to that row rather than inventing a second connection concept. - The statement half, designed and not yet built. ADR-694 (Proposed, planned) declares the
canonical
StatementDeliveryandReportedLine(D1–D3) andFormatProfileattaching as one more reader (D9). Today’s import path is ADR-094’sImportStatementCommandwith its parsers; ADR-694 reshapes the payload those parsers produce. - Simulators that produce real artefacts, capability-gated. ADR-727 D7’s return simulator
writes a real return file with the
SIMULATED-prefix; ADR-766 D4 delivers a simulated feed in the tenant’s own layout; both run as day-end steps withRequiresSimulation => trueon the tenant’s simulation flag. ADR-728 D3 records why a simulator never stands in for a human control. - Feed ingest.
Mt940Parser,Camt053Parser, CSV and BAI2 readers;FormatProfilewith an AI-authored, human-approved mapping from a sample file (ADR-094);ExpectedItemmatching; exception items toLedgerTM.Suspense. - The identity frame.
IdentityFrame.SystemActingAs(ADR-728, corrected at UAT) records that the system originated an act while naming the actor; ADR-376 D9’s service token carries the System identity over HTTP for an unattended internal caller. - Nothing card-shaped. The word card in the code means a rate card or an approval card;
Authorisationmeans four-eyes (LedgerTM.Authorisation,AuthorisationTargetRef,RequestAuthorisation). The scheme’s word for approving a purchase collides with the platform’s word for approving a change, and the collision is resolved by name below.
Scope
This ADR covers:
- The contract types in
LedgerTM.Contracts/Cardsfor the four crossings: authorisation request and decision, authorisation reversal, card command and credential, token provisioning, and the clearing item. - The processor as an
InstitutionConnectiontransport, authenticated by ADR-821’s machine principal, one connection per tenant. - The inbound doors: the authorisation decision endpoint, the reversal endpoint and the token
provisioning endpoint, each dispatching an
IExternallyAuthenticatedCommandto a decider seam that a later ADR implements. - The outbound
ICardProcessorseam and its Paymentology adapter, against the Companion API shape. - The clearing file received into the inbound file store and imported as a Cards-owned clearing batch per business date, with the typed clearing item the processor’s mapper produces.
- The Paymentology simulator: the same seam in-process, driving both directions, producing a
real
SIMULATED-clearing file at day-end. - The build-time test that refuses a PAN anywhere on the contract surface.
- The
cards.issuingfeature key and the settings row for the processor connection.
Out of scope: the card aggregate, its lifecycle and controls (next ADR); the oracle’s decision logic, the hold and the per-account holds projection (the ADR after); any account type; disputes; the acquiring feed and merchant settlement; stand-in balance push; a second processor; Amex.
Decisions
1. The seam is a boundary in LedgerTM.Contracts/Cards, and nothing above it names Paymentology
Every type a later card ADR compiles against lives in LedgerTM.Contracts/Cards, named in the
scheme’s vocabulary and not the processor’s. The Paymentology adapter maps in both directions
and is the only code that knows a Paymentology field name: outbound, our card commands into its
API; inbound, its authorisation, reversal, provisioning and clearing shapes into ours. The
inbound doors therefore bind a processor-kind body chosen by the connection’s kind, and the
mapper mints our ids from the processor’s references, so one authorisation has one id whichever
way it arrived. A second processor is a second adapter behind the same types.
The corporate proposal set the rule for Connectivity, and ADR-694 D1 applies it to statements: a consumer above the boundary cannot tell which institution spoke. The same property here is what makes the simulator honest: it implements the same seam the adapter does, so a test that passes against the simulator exercises the code a bank will run.
2. The scheme’s authorisation is a CardAuthorisation, never an Authorisation
Authorisation is taken: it means a four-eyes approval of a change (ADR-197, ADR-780). A
purchase authorisation is a different thing with a different lifecycle, and giving it the bare
word would make every later event and permission key ambiguous to the reader and to the
PermissionKey.For derivation. Every type here carries the Card prefix:
CardAuthorisationRequest, CardAuthorisationDecision, CardAuthorisationReversal.
3. The processor is an InstitutionConnection with a ProcessorApi transport
ADR-821 D1 declares one settings row per institution we exchange with, carrying its transport,
and says a feature attaches its own facet keyed by the connection. A card processor is such an
institution. This ADR uses the ProcessorApi transport ADR-821 seeds, and adds a
CardProcessorSettings facet keyed by the connection that carries what a processor needs
beyond identity: the processor kind (Paymentology, Simulator), its environment, its base
address, the credential it presents outbound (a secret reference, ADR-811), the settlement
account and operating entity its clearing is a statement of, and the decision budget.
One connection per tenant, nothing shared. BINs are not here: they are rows on the card product, which the next ADR owns, and this ADR places no ceiling on how many a tenant has.
Why not a settings row of its own, unrelated to InstitutionConnection. Because ADR-821 D1
says every feature attaches a facet to the one row, and a card processor that is not an
institution connection would be the second mechanism the corporate proposal refused. The cost
is a dependency: ADR-821’s bite 2 lands before this ADR’s bite 2 starts. That is a design-time
sequencing, recorded in the plan, not a cross-lane choreography.
Kind Simulator is valid only on a tenant whose simulation is enabled, as the capability
provider decides it, which also refuses simulation in a Production environment. The settings
validator refuses the kind otherwise, and the simulation facet is never a template row: it is
seeded in the simulation phase beside the simulation principal, so a production tenant
provisioned from the same package never carries it. The adapter for a tenant is resolved from
the facet’s kind at call time, because kind is per-tenant settings and a registration cannot
choose it.
4. Inbound calls authenticate as ADR-821’s machine principal, and run as the connection
The processor calls three endpoints: decide an authorisation, reverse an authorisation, decide a
token provisioning. Each arrives in ADR-821’s connection frame: the gateway validated the
processor’s client-credentials token, resolved its machine principal to the tenant and the
connection, and minted the identity token that names both. Each dispatches a command marked
IExternallyAuthenticatedCommand running as that connection. None is [PublicEndpoint]; none
is ISystemCommand, because the caller is not UserId.System. The day-end lock passes the
external origin (ADR-821 D4), which is what lets an authorisation be answered while day-end
runs.
None is four-eyes eligible, and the derivation says so, not this ADR. ADR-821 D5 adds the
marker as a fifth term: eligible iff ICommand && !ISystemCommand && !IFourEyesControlCommand && !IExternallyAuthenticatedCommand. A command carrying the marker is
excluded by the rule, not by assertion.
How a client id resolves to a tenant is ADR-821 D2’s, not decided here. It was ADR-694’s
gap (F-1562): a token must resolve its tenant before any tenant settings can be read. ADR-821
binds a machine principal to one tenant and one connection at platform level; this ADR assumes
only that the identity token carries tenant_id and the connection, which ADR-821 D3 mints.
Permission keys are stated, not derived (ADR-766 D7): cards.decide-authorisation,
cards.reverse-authorisation, cards.decide-token-provisioning, held by the connection’s
identity and grantable to no human; each carries an // externally-authenticated: note in the
catalogue in the style of the existing // system-internal: ones.
5. Every inbound door answers once, inside a budget, and never late
The processor’s own reference is the idempotency key, and a pending receipt is committed
before anything decides. An authorisation request keys a CardAuthorisationReceipt by the
processor’s authorisation reference; a token provisioning request keys a
CardTokenProvisioningReceipt by its provisioning reference. The door commits the receipt as
Pending in its own unit of work before it consults the decider, so two identical requests in
flight serialise on that insert: the loser finds a pending receipt and waits for the outcome,
up to the budget, then answers NotAnswered. A repeat of an answered receipt is answered from
it without consulting the decider, whatever body the repeat carries; a repeat of a NotAnswered
one is answered NotAnswered again, because the processor has already stood in for it. A body
with no reference, or a value that cannot be read, is refused as a bad request and no receipt is
written; a decider that throws or answers nonsense yields Declined with DecisionFailed.
A decision that misses the budget is refused, recorded, and discarded. The connection’s
decision budget (default two seconds) bounds the decider through a cancellation token. At the
budget the door marks the receipt NotAnswered, then replies HTTP 503 with no decision body, so
the processor stands in at once rather than at its own timeout; a decision that arrives later
is discarded. The decider returns a decision and writes nothing into the door’s unit of work,
so a late decision cannot commit a hold the processor never saw. The receipt is what tomorrow’s
reconciliation matches a stand-in clearing line against.
The request carries what the cardholder saw as well as what the account pays. The processor
converts a foreign transaction to the card’s billing currency before it asks us, so
CardAuthorisationRequest carries the billing amount and currency, and beside them the original
amount and currency, the merchant category code, merchant name and country, channel, entry mode,
whether the card was present, the card’s token reference, the processor’s authorisation reference
and the transaction’s local date.
A reversal is its own receipt naming the authorisation it reverses; an unknown one is
accepted. A reversal records a CardReversalReceipt keyed by the processor’s reversal
reference, naming the authorisation, the amount reversed and the connection that sent it; the
authorisation receipt is never rewritten. A reversal of an authorisation never seen is recorded
with outcome UnknownAuthorisation and accepted, because the processor’s record outranks ours
and a refusal would leave the processor holding a reversal we will meet in the clearing file
anyway. A second reversal of the same authorisation is a second receipt.
The deciders are seams, ICardAuthorisationDecider and ICardTokenProvisioningDecider in
LedgerTM.Contracts/Cards. This ADR ships neither: with none registered, the authorisation door
declines every request with reason IssuerNotReady and the provisioning door answers Decline.
The oracle ADR registers the real ones. The component tests here register scripted ones.
6. Outbound card commands go through ICardProcessor, and the reply is a credential without a PAN
ICardProcessor in LedgerTM.Contracts/Cards carries the request-and-reply crossings: create a
card, reissue it (same number with a new expiry, or a new number after loss), set its status,
set its controls, order plastic, close it, and fetch the clearing file for a business date. It
is resolved per tenant from the facet’s kind, and every caller lives in the cards feature
projects until a Contracts resolver is declared. Each card reply is a CardCredential: the
processor’s token reference, the BIN, the last four, the expiry month, and the credential kind
(Plastic, Virtual, DeviceToken). The adapter maps the Paymentology response
and drops everything else; a PAN in a response is never deserialised into a field, because no
field exists to hold it.
The controls the processor is told about are the ones it enforces at its switch (channel switches, per-transaction ceiling) so that a declined transaction never reaches us; the oracle still evaluates them, because a processor’s controls are a copy and ours are the record.
7. The clearing file becomes a clearing batch that Cards owns
The processor’s daily clearing file is a statement of what it did on our behalf, and the draft put it through the bank-statement file door. That does not hold: a bank statement demands an opening and closing balance the file does not carry, its import fires matching into Suspense, and the settlement account would carry two statements a day, its bank’s and the processor’s. So the file is received exactly as every other inbound file is (ADR-337, ADR-766 D4), and what it becomes is Cards’ own.
A common fetch step, run at day-end for every business date since the last file, asks
ICardProcessor for the file and receives it into the inbound file store under purpose
cards.clearing and the business date of the items it reports, skipping a date whose file
already exists. A common import step resolves the day’s file, maps it through the processor’s
adapter into CardClearingItems, and writes one CardClearingBatch document per connection and
business date, keyed deterministically, carrying the file’s id and version, the items, and
whether it was simulated. A repeat run of the same day rewrites the same batch from the same
file. An empty day is an empty batch. Matching items to holds is the oracle ADR’s, and it reads
the batch.
A real processor publishes the file for business date D on the morning of D+1, so the run for D+1 fetches and imports D’s file, and a Monday run fetches Saturday’s and Sunday’s, because cards clear on days the ledger does not open. The file is keyed by D, because a reconciliation that matches items to holds by business date must not read a run date.
The processor’s real-time transaction stream is not ingested here or anywhere: Paymentology itself says it cannot be used for financial reconciliation. The clearing batch is the ledger’s source.
8. The simulator is the processor, in-process, both directions, and it writes a real file
PaymentologySimulator implements ICardProcessor and is resolved as the adapter when the
tenant’s facet says kind Simulator. It allocates a token reference, a BIN and a last four for
every card it is asked to create, and it keeps its own record of what it authorised.
Its inbound half is four system-internal commands, dispatched by the component tests and
never routed over HTTP: simulate a card’s creation, an authorisation, a reversal, a provisioning. Each refuses to
run unless the tenant’s kind is Simulator and simulation is enabled, and each dispatches the
real inbound command in IdentityFrame.ForConnection as the tenant’s simulation principal
(ADR-821’s seed step). The demo drives the real HTTP doors with a development machine token,
as the processor would.
At day-end, SimulateCardClearingStep (RequiresSimulation => true) writes the day’s clearing
file from the simulator’s record into the inbound file store, named with the SIMULATED-
prefix ADR-727 and ADR-766 established, for the business date being closed; the common fetch
step then finds a file already present and skips, and the common import step reads it. One
import path, one difference: where the bytes came from. Formatting is the adapter’s mapping run
backwards, so the round trip is the mapper’s own test. On the simulation tenant the run for D
imports D’s own file rather than D−1’s, because the simulator has no overnight to wait for.
The simulator never stands in for a human control (ADR-728 D3). There is none here to stand in for.
9. No PAN, enforced at build time
NoPrimaryAccountNumberTests in the architecture suite walks every type in
LedgerTM.Contracts/Cards, every event and document in the cards feature projects as they
arrive, and the cards fixtures and card settings templates, and fails the build on a member,
parameter or property whose name has a whole segment Pan, CardNumber or
PrimaryAccountNumber other than Bin and LastFour, or on a string constant of sixteen to
nineteen digits that starts with a scheme digit and passes the Luhn check. Its walker takes a
set of types and files, so its own test plants a failing type and proves the failure. It does
not walk the whole template tree: a thousand account, deal and identity numbers there pass Luhn
by construction, and they are not card numbers.
The adapter has a runtime counterpart: any inbound payload field on an explicit list of free-text fields (merchant name, device description, embossed name) carrying more than twelve digits in total, separators ignored, is dropped before mapping, and a dropped field is a warning in the request log with its field name and never its value. References, tokens and amounts are not on that list, because a processor’s references and a payment token are long numerics and the reference is the idempotency key. The guard is for the doors’ bodies only, never the clearing file, whose merchant names round-trip through the simulator.
10. cards.issuing is the feature key
A tenant that has not bought cards has no processor facet, no doors and no page. The feature
catalogue binds the seven cards.* keys to cards.issuing, so a processor calling a door on a
tenant without the feature is refused, not declined, and the two read endpoints check the
feature themselves because the gate binds command keys. A tenant with no feature manifest has
every feature on, as the platform already behaves; a manifest that omits the key has it off.
Whether the tenant is simulated is the facet kind’s to say (Decision 3), guarded by the
capability provider.
Contracts
Ids — CardAuthorisationId, CardReversalId, CardTokenProvisioningId (each name-derived
from the processor’s reference, minted by the inbound mapper), CardTokenReference (the
processor’s surrogate for a PAN), CardClearingBatchId (derived from connection and business
date). InstitutionConnectionId is reused from ADR-821.
Contract types (LedgerTM.Contracts/Cards) — CardAuthorisationRequest,
CardAuthorisationDecision, CardAuthorisationOutcome (Approved, PartiallyApproved,
Declined), CardDeclineReason (a closed vocabulary: IssuerNotReady, CardNotActive,
ControlBreached, InsufficientFunds, NoFundingAccount, DecisionFailed),
CardReceiptOutcome (Pending, Approved, PartiallyApproved, Declined, NotAnswered,
UnknownAuthorisation, StepUp), CardAuthorisationReversal, CardCredential, CardExpiry,
CardCredentialKind, CardReissueKind, CardStatus, CardControls, CardChannel,
CardEntryMode, MerchantCategoryCode, CardTokenProvisioningRequest,
CardTokenProvisioningDecision (Approve, StepUp, Decline), CardClearingItem,
CardClearingItemKind (Purchase, Reversal, Refund, Chargeback), CardClearingBatch,
CardProcessorKind (None, Paymentology, Simulator), CardClearingPurposes, CardCreationRequest
(what ICardProcessor is asked to create), and the JSON converters MerchantCategoryCodeJsonConverter and
CardExpiryJsonConverter, so the code travels as "7011" and the expiry as "2029-09".
Interfaces — ICardProcessor (outbound: create, reissue, set status, set controls, order
plastic, close, fetch clearing file for a business date), ICardAuthorisationDecider,
ICardTokenProvisioningDecider (inbound seams, implemented by the oracle ADR).
Commands — DecideCardAuthorisationCommand, ReverseCardAuthorisationCommand,
DecideCardTokenProvisioningCommand — each IExternallyAuthenticatedCommand and
IConnectionScoped (ADR-821 D4, D5), permission keys cards.decide-authorisation,
cards.reverse-authorisation, cards.decide-token-provisioning, of the externally
authenticated kind, bound to cards.issuing. AmendCardProcessorCommand —
ISettingsCommand<CardProcessorSettings>, key cards.amend-processor.
SimulateCardCreationCommand, SimulateCardAuthorisationCommand,
SimulateCardAuthorisationReversalCommand, SimulateCardTokenProvisioningCommand —
ISystemCommand, no HTTP route, keys cards.simulate-card-creation,
cards.simulate-authorisation, cards.simulate-authorisation-reversal,
cards.simulate-token-provisioning (system-internal), refused unless the tenant’s kind is
Simulator and simulation is enabled.
Settings — CardProcessorSettings (keyed by InstitutionConnectionId: kind, environment,
base address, credential, settlement account, operating entity, decision budget).
Read documents — CardAuthorisationReceipt (keyed by CardAuthorisationId: request,
outcome, reason, approved amount, decided at, connection), CardReversalReceipt (keyed by
CardReversalId: the authorisation, amount, outcome, received at, connection),
CardTokenProvisioningReceipt (keyed by CardTokenProvisioningId: request, outcome, reason,
decided at, connection), CardClearingBatch (keyed by CardClearingBatchId: connection, business
date, file id and version, simulated, items).
Events — none. This ADR has no aggregate (ADR-766 D6 precedent); the first card event is the next ADR’s.
Queries — GetCardProcessorQuery (key cards.view-processor),
ListCardProcessorReceiptsQuery (key cards.list-receipts; every kind of receipt a tenant
answered in a period of trading dates, newest first), ListCardClearingBatchesQuery (key
cards.list-clearing; the batches by business date with their file and item count).
Consumed from LedgerTM.Infrastructure.Contracts — InstitutionConnection,
ConnectionTransport, IInstitutionConnectionFacet, IInstitutionConnectionReader,
IMachinePrincipalReader, IExternallyAuthenticatedCommand, IConnectionScoped,
IdentityFrame.ForConnection, ICurrentConnection (ADR-821); ICapabilityProvider (moved
here by this ADR from LedgerTM.Infrastructure, a namespace change); SecretReference and
ISecretStore (ADR-811).
Consumed from LedgerTM.Contracts — IInboundFileStore (ADR-337), ExternalAccountId,
OperatingEntityId.
Changed — FeatureCatalog gains cards.issuing, binding the seven cards.* keys;
ICapabilityProvider moves to LedgerTM.Infrastructure.Contracts; ADR-821’s plan
gains IInstitutionConnectionReader and IMachinePrincipalReader.ActorForAsync (additive,
before it builds).
Removed — none.
Prior art
python3 scripts/adr/prior_art.py --concept "card connectivity processor authorisation hold token clearing feed simulator Paymentology"
was run before the title existed. The three proposal documents matched; the cards proposal’s
sections 7, 8 and 11 name every concept here.
| Declared | Search returned | Verdict |
|---|---|---|
CardAuthorisationRequest, CardAuthorisationDecision, CardAuthorisationReversal, CardAuthorisationId |
RequestAuthorisation, AuthorisationTargetRef (Contracts/Authorisations): four-eyes approval of a change. The bare name is taken and means something else |
genuinely new — a purchase authorisation, prefixed Card so it can never be read as a four-eyes record (Decision 2) |
InstitutionConnectionId, InstitutionConnection, ConnectionTransport |
ADR-821 D1 (carved out of ADR-694 D13), Proposed, not yet built | extend — one new transport value and one facet; the row is reused as is |
the statement import path (ImportStatementCommand, FormatProfile) and ADR-694’s canonical delivery |
ADR-094 (built), ADR-694 (unbuilt) | not reused — pressed at the plan grill and refused: a bank statement carries balances, fires matching and belongs to one bank; the clearing batch is Cards’ own document (Decision 7) |
IExternallyAuthenticatedCommand |
ADR-821 D5 (carved out of ADR-694 bite 14): the marker for an authenticated non-human principal | reuse unchanged — the three inbound commands carry it |
CardClearingItem, CardClearingBatch, CardClearingBatchId |
ExpectedItem (BankStatements matching), AccountStatementLine (a line on a statement we issue), BankStatement (a statement of an account, with balances and matching) |
genuinely new — a processor’s cleared items for a business date, with no balances and no matching; a bank statement’s invariants and cascades are the wrong shape for it |
CardCredential, CardTokenReference |
ExternalAccountProxy, ProxyKinds (ADR-412): a proxy address for a beneficiary |
genuinely new — a proxy names an account someone pays; a credential names an instrument that spends |
CardControls, CardChannel, CardEntryMode |
HoldAuthorityBasis (Collections), ChannelParticipant (ADR-739): a person’s channel |
genuinely new — a card’s switches and ceilings; ADR-739’s channel is a client-channel concept and the word is qualified here as CardChannel to keep them apart |
MerchantCategoryCode |
nothing | genuinely new — ISO 18245; a standards-register row |
ICardProcessor |
ISubmissionChannel (Payments): an outbound rail with file generation |
genuinely new — request and reply over an API, not a file; a rail has no reply |
ICardAuthorisationDecider, ICardTokenProvisioningDecider |
IAuthorisationApprover (ADR-728: a Contracts seam into four-eyes) |
genuinely new — the same seam into a feature project shape, a different subject |
CardProcessorSettings, AmendCardProcessorCommand |
InstitutionConnectionSettings (ADR-821), MarketDataSettings and FeedDefinition (ADR-766) |
extend — the facet ADR-821 D1 invites, keyed by the connection, holding what a processor needs beyond identity |
PaymentologySimulator, SimulateCardClearingStep, the four Simulate* commands |
ADR-727 D7 return simulator, ADR-766 D4 feed simulation (DeliverFeedObservationsCommand), SimulateExchangeRateDeliveryStep, RequiresSimulation on IDayEndStep |
reuse the pattern — capability-gated step, real file, SIMULATED- prefix; system-internal commands with no route |
CardAuthorisationReceipt, CardReversalReceipt, CardTokenProvisioningReceipt, CardReceiptOutcome, CardReversalId, CardTokenProvisioningId |
InboundFileDescriptor (ADR-766), the request record of scripts/ltm (ADR-793) |
genuinely new — an idempotency and audit record for a real-time decision; neither existing record is keyed by a caller’s reference |
CardClearingItemKind |
ClearOpenItemCommand, OpenItemCleared, ReverseOpenItemClearingCommand (Suspense): clearing an open item in a suspense account |
genuinely new — clearing here is the scheme’s word for a presented card item; the enum names what kind of item was presented, not what happened to a suspense item |
CardTokenProvisioningRequest, CardTokenProvisioningDecision |
CollateralProvisionRequest (Securities): provisioning collateral on activation |
genuinely new — a device wallet asking to hold a card token; the shared word is a coincidence of English |
CardDeclineReason.IssuerNotReady |
FeatureNotReadyException (a feature switched on but unconfigured) |
genuinely new — a scheme-facing decline reason answered to a processor, not an exception raised to an operator; the two are mapped in the door, never merged |
IInboundFileStore, InboundFileDescriptor |
ADR-337’s inbound file store, used by ADR-766’s feed simulation and ADR-727’s return files | reuse unchanged — the clearing file is one more purpose, cards.clearing, keyed by business date |
ICapabilityProvider (moved) |
LedgerTM.Infrastructure/Capabilities/CapabilityProvider.cs, read by DayEndStepRegistry and hosting only |
extend — a namespace move to Infrastructure.Contracts so a feature project may ask whether simulation is enabled |
IInstitutionConnectionReader, IMachinePrincipalReader.ActorForAsync |
ADR-821’s IMachinePrincipalReader (ids only), InstitutionConnectionSettings in LedgerTM.Infrastructure |
extend — a feature project cannot read the connection row or a principal’s actor otherwise; additive to ADR-821’s plan before it builds |
ExternalAccountId, OperatingEntityId (on CardProcessorSettings) |
ExternalAccountId (ADR-348), OperatingEntityId; the same pair ImportStatementCommand takes |
reuse unchanged — the settlement account the clearing is of, and the operating entity that owns it |
SecretReference (on CardProcessorSettings) |
SecretReference, ISecretStore (ADR-811); EmailGatewaysSettings.Credential (ADR-810) |
reuse unchanged — the outbound credential named by purpose, never stored |
NoPrimaryAccountNumberTests |
VocabularyRowIdTests, StringVocabularyReferenceTests (ADR-422): build-time walkers over the contract surface |
reuse the pattern — a Cecil walker with an allowlist of two names |
IInstitutionConnectionFacet |
built by ADR-821 (D1): the seam a feature registers so a connection cannot be removed while the feature holds settings for it | reuse — the processor settings row registers a facet; nothing new is declared |
Relies on
| Symbol | What it does today | What this ADR assumes |
|---|---|---|
ICapabilityProvider |
Whether simulation is enabled for the tenant, refusing it in Production | The facet validator and the simulate commands ask it |
IInboundFileStore (ADR-337) |
Receives a file keyed by purpose and business date; a day-end step resolves it | The fetch step receives the clearing file; the import step resolves it |
IDayEndStep (its default member RequiresSimulation) |
A step that runs only on a simulation tenant | SimulateCardClearingStep |
ISettingsCommand<T> and SettingsCommandMiddleware |
Loads and saves a settings root around a handler | AmendCardProcessorCommand |
FeatureSettings (ADR-363) |
Absent key means off | cards.issuing |
InstitutionConnection (ADR-821 D1) |
A tenant settings row naming an institution, with its transport | A card processor is one row with a ProcessorApi transport and a CardProcessorSettings facet |
IdentityFrame.ForConnection (ADR-821 D4) |
Enters a frame whose origin is external, acting as the principal’s own actor | The three inbound doors run in it; the simulate commands run the real inbound command in it as the simulation principal |
ICurrentConnection (ADR-821 D4) |
The principal and connection of the current frame, empty after the first hop | The inbound handlers read the connection from it |
IExternallyAuthenticatedCommand (ADR-821 D5) |
Keeps a command out of four-eyes and away from any person frame | The three inbound commands carry it |
IMachinePrincipalReader (ADR-821, ActorForAsync) |
The actor and client id an enabled principal runs as | The simulate commands enter the connection frame as the simulation principal |
IInstitutionConnectionReader (ADR-821) |
Reads a connection row by id without referencing LedgerTM.Infrastructure |
The processor facet validates its connection |
Worked example
Fixture: the za-retail tenant (package retail-bank), simulation on, cards.issuing
licensed, one InstitutionConnection of kind Simulator. A counterparty and a card are created
by the scenario’s Given; no card exists in seeded data yet. Amounts in ZAR.
| Row | Before | After |
|---|---|---|
| Create card for the counterparty | no credential | CardCredential(token ref SIM-000001, BIN 400000, last four 0001, expiry 2029-09, Plastic); no field holds sixteen digits |
Authorisation AUTH-1: 5,000.00 ZAR, MCC 7011, card present, scripted decider says approve |
no receipt | receipt AUTH-1 → Approved, answered in under the two-second budget |
Authorisation AUTH-1 again, same id |
one receipt | same decision returned from the receipt; the decider is not called a second time |
Two AUTH-4 requests in flight at once |
— | one pending receipt; one decider call; both replies carry the same decision |
Authorisation AUTH-2, no decider registered |
— | Declined, IssuerNotReady; a receipt exists |
Authorisation AUTH-3, decider sleeps past the budget |
— | receipt AUTH-3 → NotAnswered written at two seconds, then HTTP 503 with no decision; the late decision is discarded |
Reversal of AUTH-1 |
receipt Approved |
a reversal receipt REV-1 → AUTH-1, 5,000.00, from the connection; the authorisation receipt is unchanged |
Reversal of AUTH-9, never seen |
no receipt | reversal receipt REV-2 → AUTH-9, UnknownAuthorisation; accepted |
| Day-end for 29 September 2026 on the simulation tenant | no clearing file | SIMULATED-cards-clearing-2026-09-29.csv written into the inbound store for purpose cards.clearing, business date 29 September; the fetch step skips it, the import step writes batch sim-processor/2026-09-29 with one item AUTH-1, 5,000.00 ZAR, MCC 7011, kind Purchase, simulated |
| Day-end for 29 September runs again | one batch | the same batch rewritten from the same file version; still one item |
Token provisioning PROV-1 from a device, scripted decider says step up |
— | StepUp returned; provisioning receipt PROV-1 → StepUp; PROV-1 again is answered from it |
A contract type gains string Pan |
build green | NoPrimaryAccountNumberTests fails naming the member; a member named Company or Participant does not |
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 Approve {
<<new>>
}
class Approved {
<<new>>
}
class CardNotActive {
<<new>>
}
class Chargeback {
<<new>>
}
class ControlBreached {
<<new>>
}
class DecisionFailed {
<<new>>
}
class Decline {
<<new>>
}
class Declined {
<<new>>
}
class InsufficientFunds {
<<new>>
}
class IssuerNotReady {
<<new>>
}
class NoFundingAccount {
<<new>>
}
class NotAnswered {
<<new>>
}
class PartiallyApproved {
<<new>>
}
class Paymentology {
<<new>>
}
class Pending {
<<new>>
}
class Purchase {
<<new>>
}
class Refund {
<<new>>
}
class Reversal {
<<new>>
}
class Simulator {
<<new>>
}
class StepUp {
<<new>>
}
class UnknownAuthorisation {
<<new>>
}
class ICapabilityProvider {
<<relies-on>>
}
class ICurrentConnection {
<<relies-on>>
}
class IDayEndStep {
<<relies-on>>
}
class IExternallyAuthenticatedCommand {
<<relies-on>>
}
class IInboundFileStore {
<<relies-on>>
}
class IInstitutionConnectionReader {
<<relies-on>>
}
class IMachinePrincipalReader {
<<relies-on>>
}
class IdentityFrame {
<<relies-on>>
}
class InstitutionConnection {
<<relies-on>>
}
class SettingsCommandMiddleware {
<<relies-on>>
}
Consequences
Positive
- Every later card ADR compiles against names that have been grilled once, here, and never against a processor’s field names.
- The simulator makes the whole issuing series buildable and demonstrable with no processor contract, no BIN and no bureau, which is what a speculative product needs.
- PCI DSS scope stays with the processor, and the claim is a failing build rather than a policy.
- The machine identity and the connection row are ADR-821’s and the file door is ADR-094’s, so a bank that onboards a second external system sees one pattern.
Negative / Trade-offs
- A sequencing on ADR-821: its bites 1, 2, 3 and 4 (the marker, the connection row and readers, the simulation principal, the connection frame) land before bites 2 to 5 here. No dependency on ADR-694 remains, and none on the bank-statement path: the clearing batch is Cards’ own.
- The Companion API is documented on Paymentology’s Sprint portal, the prepaid and fintech platform; a bank programme may sit on the enterprise platform with a different surface. The adapter is designed against the Companion shape; a different surface changes the adapter and nothing above it.
- Two decline vocabularies now exist in the world: ours and the scheme’s response codes. The adapter maps ours to the processor’s; the mapping is a table in the adapter and a row per reason in the guide.
The cheaper option, and why not
Skip the doors and the simulator: build the contract types and the clearing reader only, and let the oracle ADR add real-time later. About two sessions fewer. Refused because the oracle over batch is the proposal’s first decision, the doors are where the timeout and idempotency rules live, and a simulator that cannot drive an authorisation cannot demonstrate the product.
Neutral
- No aggregate, no events. The receipt is a document.
- The standards register gains rows for ISO 18245 (merchant category codes), ISO 7812 (issuer identification, the BIN) and PCI DSS v4 (scope avoidance), and names ISO 8583 as carried by the processor.
Implementation Plan
Seven bites, one land. Bites, acceptance criteria, files touched, interfaces, scenarios and status live in ADR-820-plan.md.
Notes
- Sequencing on ADR-821. Bite 2 here compiles against ADR-821’s
InstitutionConnection; bites 3 and 4 against its marker and connection frame. Either ADR-821 lands first, or/ltm-partitionputs both in one lane with 821’s bites ahead. Bite 1 has no dependency. ADR-694 is no longer on the path (corrected 2026-09-30, after the grill). - The Paymentology platform. Confirmed at the first Paymentology conversation (proposal section 12, deferred). The adapter is bite 5 and is the only thing that moves.
- What the next two ADRs take from here. The card aggregate takes
CardCredential,CardControls,CardStatusandICardProcessor. The oracle takesICardAuthorisationDecider,CardAuthorisationRequest,CardClearingItemand the receipt. - Model page.
python3 scripts/adr/model_required.py ADR-820saysMODEL: not requiredandNO PAGE: no model page covers cards, so this ADR draftsdocs/business/models/card.mdin the same land (ADR-786 D3), scoped in one line to the seam and the credential, for the operator to review. The card aggregate’s ADR extends it.
Changed during the grill
Grilled 2026-09-30 against the code, one day after drafting. What the draft said, what it says now, and why.
- The simulator’s clearing file moved from the push door to the file store and the file door. The draft delivered it through ADR-694’s push door, which takes a parsed delivery, so the Paymentology reader would never have run against the simulator’s output. It now follows ADR-337 and ADR-766: received into the inbound file store keyed by purpose and the items’ business date, resolved and imported by a day-end step through the file door with the reader. The real processor’s file is fetched by the adapter into the same store. Decisions 7 and 8, bite 6, two scenarios.
Timeoutleft the decline reasons. A decision that misses the budget sends no decision, so a decline reason for it was a contradiction. The door now writes a receipt with outcomeNotAnsweredand then replies 503, in that order, so a retry cannot race a late decider. Decision 5.- The token provisioning door gained its own receipt and idempotency. The draft defined
receipts, budgets and replay only for authorisations; the door that puts a live token on a
device had none.
CardTokenProvisioningReceipt, keyed by the processor’s provisioning reference, with the same rules. Decision 5, contracts, bite 4. - Receipt outcomes became one closed vocabulary.
UnknownAuthorisation(a reversal of an id never seen) andStepUpwere needed by the worked example and absent from the enum.CardReceiptOutcomenow lists them. A reversal stampsreversed aton its receipt, the one update a receipt ever takes; the draft never said receipts could change. - “One BIN set per tenant” was dropped. The draft disclaimed BINs and then constrained them. BINs are the card product’s; this ADR places no ceiling.
- The simulation flag stopped being a second mechanism. The draft had the connection kind
and the tenant’s simulation flag both deciding whether the simulator runs. The kind decides;
the settings validator refuses kind
Simulatorunless the flag is on. Decisions 3 and 10. - Four-eyes exclusion is now derived, not asserted. The draft said the inbound commands are not eligible; it now names the fourth term ADR-694 bite 14 adds to the derivation. Decision 4.
- The clearing file is keyed by the items’ business date, not the run date. The worked example named the file for the run date; a reconciliation matching lines to holds by date would have been off by one. Decision 7, worked example, scenarios.
- The request carries the original amount and currency beside the billing amount, so the statement can show what the cardholder saw. Decision 5.
- The receipts panel moved from the processor settings page to the connectivity deliveries area, beside the clearing files, where an operator already looks at what came from outside. Bite 7, scenario 13.
- Client id to tenant resolution was found missing from ADR-694 and filed as F-1562 rather than decided here, because deciding platform identity inside its second consumer is how two answers to one question begin. Decision 4.
Pressed and held without change: the boundary in LedgerTM.Contracts/Cards with no
processor name above it; the Card prefix over the bare Authorisation; the processor as an
InstitutionConnection and the sequencing on ADR-694 that follows; ADR-694 D18’s machine
identity; ICardProcessor returning a credential with no field for a PAN; the build-time no-PAN
test; no aggregate and no events; and the out-of-scope list, each item of which is the next
ADR’s by name.
Contradiction press: 8 pairs, resolved as listed above. Run by a fresh agent given the decisions and the worked example only. Its returned block, condensed:
- Token provisioning has no receipt, idempotency or outcome vocabulary — resolved: its own receipt and id, same rules.
UnknownAuthorisationis not in the closed outcome list — resolved:CardReceiptOutcome.- Connection kind and simulation flag both decide simulation — resolved: kind decides, flag guards the validator.
- A receipt is inserted once, yet gains
reversed at— resolved: the one permitted update, stated. - Timeout path replies before it records — resolved: receipt first, then 503, like every other outcome.
- “One BIN set per tenant” constrains what the ADR disclaims — resolved: dropped.
- The clearing file is named for the run date while keyed by business date — resolved: business date, worked example corrected.
- Four-eyes ineligibility asserted rather than derived — resolved: the fourth term named.
Corrected after the grill, 2026-09-30: the dependency on ADR-694 was replaced by a dependency on ADR-821, the platform half carved out of ADR-694 so that neither series waits on the other. F-1562 closes inside ADR-821. The clearing reader named here was itself replaced at the plan grill by the Cards-owned clearing batch; the design-grill entries above that mention a reversal stamping its receipt or the connectivity deliveries area are history, superseded by the plan-grill record below.
Changed during the plan grill
Plan grill 2026-09-30 (phase A questions from the test author, then a fresh reader over the signatures). What the ADR said after the design grill, what it says now, and why.
- The clearing file no longer goes through the bank-statement door. Decision 7 had it
imported as a statement of the settlement account. Pressed against the code: the profile-driven
import demands balances the file does not carry,
BankStatement.Importenforces closing equals opening plus net, a forged closing balance leaks into treasury and sample generation, the import fires matching into Suspense, and the settlement account would carry two statements a day. A Cards-ownedCardClearingBatchper connection and business date replaces it; matching is the oracle ADR’s. Decision 7, contracts. - The doors take a processor-kind body and an inbound mapper mints the ids. A strong id travels as a bare string, so a processor posting our contract shape would give one authorisation two ids depending on the route, and Decision 9’s field guard would have eaten the reference. Decision 1.
- A pending receipt is committed before the decider runs, so two identical requests in flight reach one decider; the decider writes nothing into the door’s unit of work; a repeat of a not-answered receipt is not answered again. Decision 5.
- A reversal is its own receipt. Stamping the authorisation receipt lost who reversed and when, and made the receipts scenario count wrong. Decision 5.
- The simulator’s facet and settlement account are seeded in the simulation phase, never a template row, because a template row lands on every tenant provisioned from the package, production included, and cannot name a settlement account that does not exist yet. Decision 3.
- Simulation is decided once, by the capability provider, which also refuses it in Production; the adapter is resolved from the facet’s kind at call time; the simulate commands check kind and capability and have no HTTP route; the file is written by a simulation-only day-end step, as the feed and return simulators do. Decisions 3 and 8.
- The fetch and import steps are replay-safe and walk calendar days: a file already present is not fetched again, a batch is rewritten from the same file version, a Monday fetches the weekend. Decision 7.
- The no-PAN rule matches whole name segments and scheme-shaped Luhn numbers, over cards
surfaces only. As written it failed the build on a thousand seeded account and identity
numbers and on every
panels:key. Decision 9. - The feature key gates the doors: a processor calling a tenant without
cards.issuingis refused, not declined; a tenant with no manifest has every feature on. Decision 10. - Contract shapes fixed before they freeze: a year-month expiry, a reissue kind instead of a
boolean named for the PAN, a local transaction date on the request, ISO 3166 alpha-2 for the
merchant country,
DecisionFailedfor a decider that throws or answers nonsense, and the rule that everyICardProcessorcaller lives in the cards projects. Decision 6, contracts. - Cards reads the connection row, the simulation flag and a principal’s actor through
Contracts:
ICapabilityProvidermoves toInfrastructure.Contracts, and ADR-821’s plan gainsIInstitutionConnectionReaderandIMachinePrincipalReader.ActorForAsyncbefore it builds. - The purpose is
cards.clearing, the file is a.csv, and Cards carries its ownSIMULATED-constant. - Phase B corrections (seven test authors, 2026-09-30): four simulate commands, not three,
each with a system-internal key; the provisioning receipt carries a reason; a
Noneprocessor kind so an undeclared facet never reads as a live processor; the twelve-digit guard counts digits in total and never touches the clearing file; the seven keys bind to the feature and the reads check it themselves; the clearing mapper lives under the processor folder so no Paymentology name sits above the seam; the fetch walk starts at the day after the last batch or seven days back; a simulation tenant is one whose facet kind isSimulator; day-end walks every calendar day already, so the walk covers missed days rather than weekends as such.