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-836: Cards and Authorisation: the authorisation oracle and the card hold

Status: Shipped — 2026-10-03


Context

The Problem

ADR-820 shipped the door a processor knocks on, and ADR-835 shipped the card it asks about. Between them nothing decides. Every authorisation is still answered IssuerNotReady, because no decider is registered: the seam ICardAuthorisationDecider has no implementation, no hold exists, and an account knows nothing of money a cardholder has committed at a till.

The proposal (§4.1–4.3, pinned at its grill) decides the shape. The oracle answers in milliseconds from the ledger: card status, controls, then an ordered funding rule walked to the first account whose available covers the amount, the whole hold on that account, never split. The hold lives on the card’s stream, not the account’s (ADR-251’s claims are released only by a day-end step, and a tap must not wait for midnight); the account learns of it through an inline projection keyed by account; release is real time on a reversal, at clearing, or by a day-end step at the merchant-category expiry. The clearing line is the posting; the authorisation never moves money.

What Already Exists

Scope

This ADR covers:

Out of scope: the current account, the overdraft facility and the posting that outranks the guard (the current account ADR — until it lands a clearing item the guard refuses is an exception here, and a facility counts toward available only where an account type already integrates one); card fees including the foreign-transaction fee; chargebacks and disputes (the dispute ADR — a Chargeback clearing item is an exception); corporate just-in-time pooled funding beyond the ordered walk; fraud scoring (the processor’s and the scheme’s); incremental authorisations (a hotel or car hire topping up an authorisation under new references), which are each their own hold until expiry and so can over-reduce available for the thirty-day categories until a later ADR links them.


Decisions

1. The oracle checks in a fixed order, and each refusal has one reason

CardAuthorisationDecider implements ADR-820’s seam. For a request it answers, in this order, stopping at the first failure:

Check Decline reason ISO 8583
the token resolves to a card UnknownToken 14
the card is Active CardNotActive 62
the credential presented has not expired: good through the last day of its expiry month (a closed credential has already left the token index, so it is unknown) CredentialExpired 54
the request bills in the card’s currency (a processor fault otherwise, logged) DecisionFailed 96
the switch for this tap is on: the request’s card-present flag decides presence; ATM needs the ATM switch alone, a card-present tap the in-store switch and, for a contactless entry, the contactless switch; a card-not-present tap the online switch ChannelNotAllowed 57
a card-present tap (an ATM abroad included) outside the processor facet’s domestic country: in-store abroad on, or inside the travel window; no domestic country set, no check CountryNotAllowed 57
the amount is within the per-transaction ceiling, and today’s and this month’s spend plus the amount within the daily and monthly ceilings CeilingExceeded 61
the funding rule names an account that is open and active NoFundingAccount 52
some account in the rule covers the amount, or partial approval applies (Decision 4) InsufficientFunds 51

ControlBreached (ADR-820) is superseded by the three control reasons above; it had one code and three causes, and a clerk explaining a decline needs the cause. It stays in the enum as a plain member nothing produces (an obsolete mark is a build error under warnings-as-errors), so a stored receipt still reads. A request whose billing currency is not the card’s is a processor fault: DecisionFailed, logged. The domestic country is a setting on the processor facet (ADR-820’s CardProcessorSettings gains DomesticCountry). The day for a daily ceiling is the tenant’s trading date and the month its calendar month (ADR-835 D6); spend is the sum of the amounts approved on the card’s holds placed in the period, whatever became of them since, net of reversals; a declined tap is not spend. It is a sum over the card’s hold documents by the date placed.

Fraud scoring is not in the list: the processor and the scheme run it before the message reaches us (proposal §4.2). Currency is not in the list: the processor has converted to the billing currency, and every funding account is in it (ADR-835 D5).

2. The hold lives on the card’s stream and is placed with the approval

An approval places a hold: on the card’s own stream, CardHoldPlaced with the authorisation id, the funding account the walk chose, the approved amount, the billing currency, the merchant category, the trading date, and the expiry date. The decider appends it in its own unit of work, under a token that is not the door’s budget, and commits before it answers, so the hold is in force the moment the decision leaves. Two taps on one card serialise on the card’s stream; a concurrency conflict retries the decision once from the top, against the new state.

The decider writes nothing into the door’s unit of work (ADR-820 D5). The receipt is the door’s, the hold is the card’s, and the two are reconciled by the authorisation id: a repeat is answered from the receipt and never reaches the decider, so no second hold is placed; a decision the door could not answer in time (NotAnswered) has placed a hold the processor may or may not have honoured, because its stand-in rules decide in our silence and we never learn which way. The hold stays and ends like any other hold: by a reversal, by the clearing line, by expiry, or by the card’s closure (Decisions 5 to 8). The customer may see money committed for a few days on a tap the stand-in declined; the bank never pays a stand-in approval twice (grill, 2026-10-02: the operator chose this over releasing at once).

Why the card and not the account (proposal §12): an account’s claim is an event on the account’s stream, released only by a day-end step; a tap would contend with the day-end walk and a merchant reversal at 14:00 would wait for midnight. On the card the release is a command, now.

3. The account learns of card holds through one seam, wherever a claim counts

Every hold is an inline document of its own, CardHold, keyed by the authorisation: card, funding account, original and remaining amount, dates, status and what released it. One document per hold, never one per account: two cards tapping on one account at once must not lose a hold to a shared document with no optimistic check. Cards implements a Contracts reader over those documents, IAvailableBalanceReductionsReader: for a set of accounts and a day, the amount by which something outside the account reduces its available. Accounts injects every such reader and sums them — a host without Cards reduces by zero, a second holder joins — and reads them wherever it projects available balance today: AvailableBalance.Project gains the reductions as a required third input, so a withdrawal at a branch, an instruction, a workflow guard, the balance resolver and the account detail all see “held by cards” beside the account’s own claims. The account’s events and stream are untouched; the figure is a read.

The concept is ADR-251’s generalised one step: a dated hold against available balance, held by another aggregate. The reader is named for the concept, not for cards, so a later holder (a guaranteed cheque, a pending payout) joins it rather than adding a second seam.

4. The funding walk takes the whole amount from the first account that covers it

The decider reads the card’s funding rule (ADR-835 D5) and, for each account in order, asks Accounts for its available through IAccountAvailabilityReader: the sum of the account’s standard positions after claims and after external reductions. A facility’s available joins that sum with the current account ADR, which attaches the first one; no retail type integrates a facility today, so this ADR touches neither Limits nor a facility seam. The first account whose available covers the amount takes the whole hold. Nothing is split (proposal, pinned: two postings for one receipt).

Partial approval. CardAuthorisationRequest gains PartialApprovalAllowed (the scheme’s flag, from the processor’s body). When it is set and no account covers the amount, the first account in the rule with available above zero takes a hold for its available, and the decision is PartiallyApproved with that amount. When it is not set, the answer is InsufficientFunds.

The read is one query per account in the rule, inside the door’s budget; a rule of three accounts is three reads and one append. ResolveAccountBalanceQuery stays for its callers and the reader is the same computation with the facility added.

5. A hold is released in real time by a reversal, and reduced by a partial one

ADR-820’s reversal door records its receipt; once that commits it cascades ReleaseCardHoldCommand(hold, reason, released-by, amount?), naming the reversal that caused it, so the stream says on whose authority the money was freed. With no amount the hold is released (CardHoldReleased, reason Reversed); with an amount below the hold the hold is reduced (CardHoldReduced) and the remainder stays. A reversal for an authorisation with no hold (unknown, expired, already cleared) changes nothing: the receipt already says UnknownAuthorisation or the hold is gone, and both are legitimate.

6. The clearing line is the posting; the hold is released when it posts

A day-end step of its own, PostCardClearingStep at order 44 (before expiry at 45), posts every batch that still has an unsettled item — one without an outcome, one whose outcome is an exception, or one posted whose hold is still open — and records an outcome per item on the batch: the transaction posted and its account, or the exception and its code. A step that dies halfway resumes by item on the next run; an exception is retried at every day-end, so a line refused on a closed account posts when the account reopens; Accounts skips a transaction id it has already posted, so a line never posts twice. The import stores batches, merging a re-imported file’s outcomes by reference, and does nothing else. For each item, in file order:

The posting commands are system commands in Contracts/Accounts beside ProcessBankDepositCommand; Accounts runs them as the account type’s cardPurchase and cardRefund external integrations, each naming an operation that posts transaction type CardPurchase or CardRefund, which the retail package’s fundable account types gain. The posting is configuration on the type, as every external source is. The transaction id is derived from the processor’s reference, so a re-imported file posts nothing twice.

7. A hold expires at day-end, by merchant category

CardHoldExpirySettings holds a default (seven days) and rows by merchant-category range (hotels 7011 and car hire 7512: thirty; fuel 5541–5542: three), per tenant, as the scheme rules have them. Ranges are inclusive, disjoint (a narrower exception is a split band, not an override) and at most thirty-one days, in calendar days from the trading date. A hold’s expiry date is set when it is placed. ExpireCardHoldsStep (order 45, after the clearing post so a line arriving that day releases first) releases every hold whose expiry date is on or before the trading date being closed (Expired): a seven-day hold placed on the 2nd is released at the close of the 9th. The settings are rows nothing else refers to, so they carry no id (ADR-422).

8. Closing a card releases its holds; a hold never outlives its card

CloseCard (ADR-835) releases every open hold on the card (CardClosed). A clearing line for one of them arrives later as an unmatched item and posts to the first funding account (Decision 6): the bank paid the scheme, and the account’s owner still owns the debt.

9. The oracle reads one document and writes one stream

Everything the decider reads is on the card’s summary or the card’s own hold documents plus one availability read per funding account. It writes only the card’s stream. That is the budget’s shape: no cross-feature command, no account stream touched, and the account’s own guard never runs at a tap.

10. Permissions, feature and four-eyes

The oracle has no human verbs. System-internal keys: cards.release-card-hold, cards.expire-card-holds, cards.post-card-clearing-batch, accounts.process-card-purchase, accounts.process-card-refund. Settings: cards.amend-hold-expiry, cards.view-hold-expiry. Reads: cards.list-card-holds, bound to cards.issuing and checked by the query. Every mutation on a card or an account is a system command the processor, the clearing file or day-end causes, so none is four-eyes eligible; the one human verb, amending the hold-expiry settings, is eligible as every settings command is, and should be: cutting the hotel band from thirty days to one frees committed money.

11. The UI and the guide

The card viewer gains a Holds panel (open holds with merchant, amount, placed on, expires on; released holds with their reason). The account viewer’s available-balance breakdown shows Held by cards beside the account’s claims. The hold-expiry settings page sits under reference data. The cards guide article gains the holds section and the account article the held-by-cards line.


Contracts

Ids — CardHoldId (equal to the CardAuthorisationId it answers; one hold per authorisation; incremental authorisations under new references are each their own hold, see Out of scope).

Values — CardHoldReleaseReason (Reversed, Cleared, Expired, CardClosed), CardHoldStatus, CardHoldExpiryRule (merchant-category range, days), CardClearingItemOutcome (item reference, the transaction and account posted, or the exception code and message), CardClearingException (its view).

Settings — CardHoldExpirySettings (default days, rows of CardHoldExpiryRule).

Commands — ReleaseCardHoldCommand, ExpireCardHoldsCommand, PostCardClearingBatchCommand (ISystemCommand, in LedgerTM.Cards); ProcessCardPurchaseCommand, ProcessCardRefundCommand (ISystemCommand, in Contracts/Accounts, handled by Accounts); AmendCardHoldExpiryCommand (ISettingsCommand<CardHoldExpirySettings>).

Events — on the card’s stream: CardHoldPlaced, CardHoldReduced, CardHoldReleased; on the account’s stream, by Accounts: the existing transaction events with the two new types.

Queries — ListCardHoldsQuery (by card: open and released holds), GetCardHoldExpiryQuery.

Read documents — CardHold (inline, one per hold: card, account, amounts, dates, status, what released it; the reductions reader, the expiry step and the spend ceilings all query it); CardClearingBatch gains Outcomes. Card gains an inline snapshot so a tap loads a document, not its history.

Interfaces — CardAuthorisationDecider implements ADR-820’s ICardAuthorisationDecider. New in Contracts: IAvailableBalanceReductionsReader (Cards implements; Accounts injects every one and sums), IAccountAvailabilityReader (Accounts implements; Cards reads).

Consumed from LedgerTM.Contracts — ResolveAccountBalanceQuery (unchanged, beside the reader), IAccountReferenceProvider. Consumed from LedgerTM.Cards — ICardByTokenReader, CardSummary, CardAuthorisationRequest, CardAuthorisationDecision, CardClearingBatch, CardClearingItem. Each lived in Contracts when this ADR shipped, and moved to its only reader on 2026-10-21 (ADR-755 ruling).

Changed — CardDeclineReason gains ChannelNotAllowed, CountryNotAllowed, CeilingExceeded, CredentialExpired; ControlBreached stays, obsolete. CardAuthorisationRequest gains PartialApprovalAllowed. CardClearingBatch gains Outcomes. CardProcessorSettings (ADR-820) gains DomesticCountry, optional. SimulateCardAuthorisationCommand (ADR-820) gains PartialApprovalAllowed and Clears, so the simulator can leave an approval uncleared and the demo can show a hold expire. MerchantCategoryCode’s converter answers a malformed code as a bad request. TransactionPosted (Accounts-internal) gains Properties (the merchant), and the external-source dispatch context carries them. AvailableBalance.Project (Accounts-internal) gains external reductions and loses its two-argument form, so every caller passes them.

Removed — none.


Prior art

Declared Search returned Verdict
CardAuthorisationDecider ICardAuthorisationDecider (ADR-820, no implementation), CardTokenProvisioningDecider (ADR-835) implements — the seam’s first implementation, shaped like the provisioning decider
CardHoldPlaced, CardHoldReduced, CardHoldReleased, CardHoldId, CardHoldReleaseReason ClaimRaised, ClaimReleased, Claim (ADR-251: a hold on the account’s own stream); HoldAuthorityBasis (Collections: a hold on an account for collections) genuinely new — the same concept held by another aggregate; ADR-251’s claim is released only at day-end and lives where a tap must not write
CardHold, CardHoldStatus, IAvailableBalanceReductionsReader AvailableBalance.Project (Accounts), IHeldAccountsReader (a different “held”), CardAuthorisationReceipt (keyed the same way, a decision’s record) genuinely new — the first reduction of available balance from outside the account, one document per hold; named for the concept so a second holder joins it
IAccountAvailabilityReader ResolveAccountBalanceQuery (ADR-040 era: standard positions after claims) extend — the same sum, through a Contracts reader, plus the facility the type integrates
CardClearingItemOutcome CardClearingBatch (ADR-820), the request record’s per-request outcome (ADR-793) genuinely new — the batch’s per-item record, so a re-run resumes by item
ReleaseCardHoldCommand, ExpireCardHoldsCommand, PostCardClearingBatchCommand ADR-820’s clearing step commands, MirrorCardToProcessorCommand (ADR-835) reuse the pattern — cascaded system commands
ProcessCardPurchaseCommand, ProcessCardRefundCommand ProcessBankDepositCommand, ProcessCashWithdrawalCommand (ADR-049 external sources) extend — two more external-source postings in the same file
CardHoldExpirySettings, CardHoldExpiryRule, AmendCardHoldExpiryCommand, GetCardHoldExpiryQuery HoldDays per settlement rail (ADR-251 D4, EditSettlementRail) reuse the pattern — a hold’s life as tenant settings, here banded by merchant category
CardClearingException CardClearingBatch (ADR-820) extend — the view of an outcome that carries a code
ListCardHoldsQuery ListCardProcessorReceiptsQuery (ADR-820) reuse the pattern
PostCardClearingStep ImportCardClearingStep (ADR-820: a step that resumes by what is missing) reuse the pattern — a replay-safe step over the batches, resuming by item
TransactionPosted.Properties TransactionPosted (Accounts), the account’s property bag extend — the merchant on the posting, as properties
ExpireCardHoldsStep NoticeExpiryStep (Accounts), SimulateCardClearingStep (ADR-820) reuse the pattern — a day-end expiry over one feature’s records
CardDeclineReason.ChannelNotAllowed, CountryNotAllowed, CeilingExceeded, CredentialExpired CardDeclineReason.ControlBreached (ADR-820) extend — one code with three causes becomes three, plus the expiry the oracle checks; the old member stays obsolete
CardProcessorSettings.DomesticCountry CardProcessorSettings (ADR-820), IsoCountryCode (ADR-386), TenantProvenanceSettings.CountryLayer (set only at provisioning) extend — the facet knows the processor’s domestic market
SimulateCardAuthorisationCommand SimulateCardAuthorisationCommand (ADR-820), CardAuthorisationRequest, CardAuthorisationReceipt extend — gains PartialApprovalAllowed and Clears; same command, two more knobs
MerchantCategoryCode MerchantCategoryCode, MerchantCategoryCodeJsonConverter (ADR-820) extend — the converter answers a malformed code as a bad request instead of a server fault
CardAuthorisationRequest.PartialApprovalAllowed CardAuthorisationRequest (ADR-820) extend — the scheme’s flag
CardAuthorisationId CardAuthorisationId (ADR-820: minted from the processor’s reference) reuse unchanged — the hold’s id is the authorisation’s
ICardByTokenReader, CardSummary, CardAuthorisationRequest, CardAuthorisationDecision, CardClearingBatch, CardClearingItem, ResolveAccountBalanceQuery, IAccountReferenceProvider Contracts reuse unchanged

Relies on

Symbol What it does today What this ADR assumes
ICardAuthorisationDecider The door calls it inside the budget; none registered means IssuerNotReady This ADR registers the one implementation
ICardByTokenReader Token reference → CardId (ADR-835) The oracle’s first read
CardSummary Status, credentials, controls, travel window, funding rule (ADR-835) What the oracle checks against
AvailableBalance Projects available per position from ledger and claims Gains external reductions as an input
ResolveAccountBalanceQuery Available of the standard positions after claims The availability reader is the same sum plus the facility
ProcessBankDepositCommand A system posting from outside Accounts The two card postings follow it
CardClearingBatch One batch per connection and business date (ADR-820 D7) The post step reads it and records an outcome per item
IDayEndStep A step with an order and a criticality PostCardClearingStep at 44 and ExpireCardHoldsStep at 45, non-critical
SimulateCardAuthorisationCommand Drives the real door as the simulation principal (ADR-820 D8) The demo and the tests

Worked example

Fixture: the za-retail tenant, simulation on, processor kind Simulator; the demo customer’s active virtual debit card (ADR-835’s sample card) funded from their CallDeposit holding 4,200.00 ZAR, no facility; a second CallDeposit holding 500.00 later in the rule. Hold expiry: default 7 days, hotels (7011) 30. Trading date 2 October 2026.

Row Before After
Groceries 1,200.00 at 5411, card present, chip, ZA available 4,200.00 Approved; hold 1,200.00 on the call deposit, expires 9 October (released at the close of the 9th); available reads 3,000.00 on the account detail and the balance resolver
Hotel 5,000.00 at 7011 available 3,000.00 the first account’s available 3,000.00 does not cover; the second’s 500.00 does not; Declined, InsufficientFunds (51); no hold
Hotel 5,000.00 at 7011 with partial approval allowed available 3,000.00 PartiallyApproved 3,000.00; hold 3,000.00 expiring 1 November
Reversal of the hotel for the full amount at 14:00 hold 3,000.00 CardHoldReleased, Reversed; available 3,000.00 again, at 14:00
Online 200.00 with online off — Declined, ChannelNotAllowed (57); nothing touched
In-store in GB with in-store abroad off and no travel window — Declined, CountryNotAllowed (57)
The same in GB inside a travel window for GB — Approved
A 2,500.00 tap with a per-transaction ceiling of 2,000.00 — Declined, CeilingExceeded (61)
Day-end 2 October: the simulator’s clearing file carries the groceries at 1,150.00 hold 1,200.00 CardPurchase 1,150.00 posted to the call deposit, value date 2 October, Dr deposit liability / Cr card settlement payable; hold released Cleared naming the line; ledger 3,050.00, available 3,050.00
A clearing item for an authorisation never seen, 80.00 at 5541 — CardPurchase 80.00 posted to the first funding account
A clearing Chargeback item — exception on the batch, nothing posted
Day-end 9 October with a 7-day hold placed 2 October never cleared hold open CardHoldReleased, Expired
A repeat of AUTH-1 (ADR-820’s door) one hold answered from the receipt; the decider is not called; one hold
A decision that misses the budget after placing its hold hold placed receipt NotAnswered; the hold stays and clears or expires like any other, because the stand-in may have approved

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 CeilingExceeded {
    <<new>>
  }
  class ChannelNotAllowed {
    <<new>>
  }
  class Cleared {
    <<new>>
  }
  class Clears {
    <<new>>
  }
  class ControlBreached {
    <<new>>
  }
  class CountryNotAllowed {
    <<new>>
  }
  class CredentialExpired {
    <<new>>
  }
  class DomesticCountry {
    <<new>>
  }
  class Expired {
    <<new>>
  }
  class Outcomes {
    <<new>>
  }
  class PartialApprovalAllowed {
    <<new>>
  }
  class Properties {
    <<new>>
  }
  class Reversed {
    <<new>>
  }
  class AvailableBalance {
    <<relies-on>>
  }
  class CardClearingBatch {
    <<relies-on>>
  }
  class CardSummary {
    <<relies-on>>
  }
  class ICardAuthorisationDecider {
    <<relies-on>>
  }
  class ICardByTokenReader {
    <<relies-on>>
  }
  class IDayEndStep {
    <<relies-on>>
  }
  class ProcessBankDepositCommand {
    <<relies-on>>
  }
  class ResolveAccountBalanceQuery {
    <<relies-on>>
  }
  class SimulateCardAuthorisationCommand {
    <<relies-on>>
  }

Consequences

Positive

Negative / Trade-offs

Neutral


Implementation Plan (Bites)

Seven bites, one land. Bites, acceptance criteria, scenarios, files touched and status live in ADR-836-plan.md.


Changed during the grill

Grilled 2026-10-02 with the operator, from the card model page and the shipped ADR-820 door.

Contradiction press: 4 pairs, resolved as — Decision 2 now names every way a hold ends (reversal, clearing, expiry, closure) instead of two; Decision 1’s funding row defers to Decision 4 for partial approval; Decision 6’s refused post is worded against that list.

Contradiction press: 4 pairs

  1. A reversal for an open hold: Decision 5 releases it; Decision 2 as written named only clearing and expiry as ways a hold ends.
  2. No account covers the amount and partial approval is allowed: Decision 1’s table said InsufficientFunds; Decision 4 says PartiallyApproved.
  3. A matched line Accounts refuses: Decision 2 said the hold clears when the line arrives; Decision 6 keeps it until expiry.
  4. Closing a card with an open hold: Decision 8 releases it; Decision 2 did not name closure.

Changed during the plan grill

Phase A (the test author’s question pass, 26 questions) and the plan grill (15 points), 2026-10-02, operator’s standing instruction to take positions:


Notes

Outcome

Landed as designed in six bites; the full box suite passed at 9bd6f23ec. Three faults in the decider shipped with it and are owed to the cards lane: F-1806 (two taps can pass a ceiling, P1), F-1807 and F-1808 (tenant-wide hold reads). D7’s back-dated accrual is proven only once ADR-837 bite 5 (F-1791) lands.