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
ICardAuthorisationDecider,CardAuthorisationRequest,CardAuthorisationDecision,CardDeclineReasonwith ISO 8583 codes, the receipt and the door’s budget (ADR-820 D5): a late or nonsense decision is already turned intoNotAnsweredorDecisionFailed.ReverseCardAuthorisationCommandand its receipt (ADR-820): the reversal arrives, nothing releases.CardClearingBatchwithCardClearingItems, imported at day-end (ADR-820 D7): the items name the authorisation, the final amount and the merchant; nothing posts them.Card,CardSummary(status, credentials with expiry, controls, travel window, funding rule),ICardByTokenReader(ADR-835).AvailableBalance.Project(ledger, claims)in Accounts, called at six sites: the detail query, the balance resolver, the availability guard, the instruction guard, the workflow interpreter. AClaimreduces one position (ADR-251 D2).ResolveAccountBalanceQuery: the available of an account’s standard positions after claims;LimitIntegrations.Facilityon an account type andFacilityCheckin Limits.ProcessBankDepositCommandand its siblings inContracts/Accounts: how a feature outside Accounts posts to an account, as a system command Accounts handles.SimulateCardAuthorisationCommandand the simulator’s clearing file (ADR-820 D8).- Day-end steps 41–43 (ADR-820) and the cards reachability and no-PAN gates.
Scope
This ADR covers:
- The decider: the fixed order of checks, each with a reason code and its ISO 8583 code.
- The hold on the card’s stream: placed with the approval, reduced or released by a reversal, released by a clearing match, expired by day-end at the merchant-category expiry.
- The per-account holds projection and the seam through which card holds reduce an account’s available balance wherever a claim does.
- The funding walk, partial approval, and the account availability read it needs.
- The clearing post: a matched item posts the purchase to the funding account and releases the hold; an unmatched item posts to the first funding account; a refused post is an exception the operator sees.
- Hold expiry by merchant category, as tenant settings.
- A holds panel on the card viewer, “held by cards” in the account’s available, and the guide.
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 token resolves to a card; the authorisation id resolves to an open hold on it.
- A matched
PurchasepostsProcessCardPurchaseCommandto the hold’s funding account for the item’s final amount (a tip or a currency difference makes the final differ from the hold), value-dated at the item’s transaction date, with the merchant name, category and country on the transaction; then the hold is released (Cleared), whole, whatever the difference. - A
Purchasewhose hold has been released (expired, reversed, closed, or already cleared — a second clearing is legal) posts to that hold’s account; aPurchasewith no hold at all (offline, below floor limit) posts to the first account in the card’s funding rule. The bank has already paid the scheme. A hold is matched by its authorisation before any token, so a reissued card’s old number still clears to the right account. - A
RefundpostsProcessCardRefundCommandas a credit to the account the matching purchase posted to, or to the first funding account. - A clearing
Reversalcredits the account its purchase posted to, as a refund does, and releases the purchase’s hold if it is still open; one for a purchase never posted is an exception. - A
Chargebackis recorded as an exception for the dispute ADR. - Every posting carries the merchant’s name, category and country, so the statement line and
the transaction history say where the money went.
CardPurchasedebits the account’s deposit liability and credits a card-settlement payable;CardRefundis the reverse. Value date is the transaction date: a live processor publishes a day late, so a live post is back-valued a day and accrues from it, as a card purchase should. - The
card-purchaseoperation declares no availability guard, so the post is unconditional: a call deposit may go below zero, which the current account ADR prices as an unarranged overdraft. A post Accounts still refuses (an inactive account, a type without the integration) is recorded as aCardClearingExceptionon the batch with the refusal’s code; the hold, if any, is not released by the refused post and ends by reversal, expiry or closure, so the money stays committed.
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
- The demo: tap, the hold appears on the customer’s account, next morning it is a posting, and the card was funded across accounts without a split (proposal, lane one).
- Every decline names its cause, mapped to the scheme’s code, so the processor, the cardholder and the clerk read the same reason.
- Available balance has one mechanism for holds from outside the account, which the next holder reuses.
Negative / Trade-offs
- The clearing post is unconditional, so a call deposit can go below zero before the current account ADR prices that as an unarranged overdraft.
- Two cards funded from one account can overcommit it in the milliseconds between two availability reads; taps serialise per card, not per account. Accepted: the exposure is one authorisation’s worth, and the clearing post is unconditional anyway.
- A funding account closed with open card holds keeps them until they expire, and its clearing lines are exceptions retried each day-end; releasing holds on account closure is later.
- The decider writes to the card’s stream from inside a request budget; a slow database is a
NotAnsweredwith its hold kept, not a wrong answer, but it is visible to the processor and to the customer as committed money until the line clears or the hold expires. ControlBreachedleavesCardDeclineReasontwo days after it shipped; nothing stored holds it beyond receipts on simulation tenants.
Neutral
- The hold’s expiry is a tenant setting, so a bank’s scheme rules are configuration.
- A card purchase is value-dated at the transaction date, so a live clearing line accrues from the day the money left, not the day the file arrived.
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.
- A hold the door could not answer for stays (Decision 2). The draft released it at once
with reason
NotAnswered; the processor’s stand-in decides in our silence and may approve, so releasing frees money the bank may already have paid. The operator chose to keep it: it ends by reversal, clearing, expiry or closure.NotAnsweredleftCardHoldReleaseReason. - Closing a card releases its holds (Decision 8, new): the draft was silent; a later line posts unmatched to the first funding account.
- Pressed and held: the hold on the card’s stream rather than an account claim (Decision 2, against ADR-251’s claim); the whole hold on one account (Decision 4, against a split); the scheme’s partial-approval flag (Decision 4); an unmatched line posting to the first funding account (Decision 6); a refused post as an exception until the current account ADR (Decision 6); the expiry bands as tenant settings (Decision 7); one reductions seam named for the concept, not for cards (Decision 3).
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
- A reversal for an open hold: Decision 5 releases it; Decision 2 as written named only clearing and expiry as ways a hold ends.
- No account covers the amount and partial approval is allowed: Decision 1’s table said
InsufficientFunds; Decision 4 saysPartiallyApproved.- A matched line Accounts refuses: Decision 2 said the hold clears when the line arrives; Decision 6 keeps it until expiry.
- 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:
- One document per hold, never one per account (Decision 3): a shared per-account document loses a hold when two cards tap at once, and nothing could find a hold by id or by expiry.
- The clearing post is its own day-end step with an outcome per item (Decision 6): a post cascaded from the import could die halfway and never run again; the step resumes by item.
- The release events carry the account, the amount freed and what released them (Decisions 5, 6): an auditor reads on whose authority the money was freed — the processor’s reversal or clearing reference, the string an operator recognises.
- The decider is one bite: a passing control has nothing to answer until the funding walk.
- The domestic country is a setting on the processor facet; null skips the check.
- The clearing post is unconditional (no availability guard on the
card-purchaseoperation): what the current account ADR adds is the unarranged-overdraft price, not the post. - The facility leaves this ADR (Decision 4): no retail type integrates one; the current account ADR brings it with its first facility.
- Every available-balance caller passes the reductions, by removing the two-argument form.
- The merchant travels with the posting, and the GL legs are named (Decision 6).
- A hold is released at the close of its expiry date, not the day after (Decision 7).
- A clearing
Reversalcredits the account its purchase posted to; incremental authorisations are out of scope with the consequence named. - Reads under the budget, the save under none: a late decision’s hold is deterministic.
ControlBreachedstays, obsolete, so stored receipts still read.- The hold-expiry settings command is four-eyes eligible (Decision 10 reworded).
Cardgains an inline snapshot: a tap loads a document, not a year of taps.- Phase B (six authors): the post step revisits a batch until every item is settled and
retries exceptions; what released a hold is the processor’s reference;
ControlBreachedstays a plain member; the simulator can leave an approval uncleared so expiry can be shown; presence is the request’s flag and an ATM abroad is card present; bands are disjoint and capped at thirty-one days; the currency check joins the order after the credential.
Notes
- Depends on ADR-820 and ADR-835 (both Shipped). The current account ADR consumes Decision 6’s exception path and turns it into a posting.
- The card model page gains the oracle’s facts at land (the (proposal) markers in its hold section come off).
- Reseed: the hold-expiry template rows and the two transaction types on the retail
package’s fundable account types (
reseed: true). - Register: ISO 8583 and ISO 18245 rows exist from ADR-820; the response-code column gains the three new reasons.
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.