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-844: Cards and Authorisation: spend controls and the corporate card
Status: Shipped — 2026-10-03
Context
The Problem
The proposal sells spend controls as the corporate expense card’s product: per-card ceilings, merchant-category and country rules, just-in-time funding from a pooled account, and a corporate administrator who issues, caps and cancels cards for their own staff (proposal §3.3, §4.2). Today a card carries five channel switches and three value ceilings, per transaction, per day and per month (ADR-835 D6), which the oracle checks (ADR-836 D1). Nothing restricts a merchant category or a country by list, nothing counts transactions, nothing ends a card on a date, and no one outside the bank can change a card.
Three gaps follow, each one a sale lost:
- A finance director cannot block gambling or cash on a staff card, or limit a travel card to the countries of a trip. That is the first thing a corporate prospect asks.
- A virtual card for one supplier — single use, a budget, valid to a date — cannot be made. That is the third shape the proposal names (Moss, Spendesk, Amex vPayment), and the oracle could make it native.
- The corporate administrator does not exist. ADR-695 built the client channel user with a closed list of operations; no card operation is on it, so every staff card is a call to the bank.
What Already Exists
CardControls(ADR-835 D6):OnlineAllowed,InStoreAllowed,InStoreAbroadAllowed,AtmAllowed,ContactlessAllowed, and three ceilings, validated byCardControlsRuleso per-transaction ≤ daily ≤ monthly. Set bySetCardControlsCommand, recorded asCardControlsSet.- The oracle’s check order (ADR-836 D1): token, status, credential, currency, channel, domestic country and travel window, ceilings, funding. Spend in a period is the sum over the card’s own hold documents by the date placed, net of reversals; a declined tap is not spend.
CardType(ADR-835):DefaultControls,FundingShape,CardholderMayDifferFromOwner,FundableAccountTypes. A corporate card is already expressible: the owner is the corporate, the cardholder a named person, the funding rule one pooled account.CardHoldExpirySettings(ADR-836 D7): hold expiry by merchant-category range, the only place a merchant category is grouped today.- The client channel (ADR-695): a channel user under one agreement, entitlements binding
operations to an account scope and an optional ceiling (D5, D11), and
ChannelCataloglisting every client-facing operation with a pinned key (D9). Channel acts are exempt from four-eyes until client approval rules ship (D13).
Scope
This ADR covers:
- A spend limit as one concept — a scope, a period, an amount and a count — replacing the three fixed ceilings.
- Merchant category groups as a tenant vocabulary, and category and country rules on a card.
- The bank’s bounds on a card type, which every other editor works inside.
- A card’s valid-until date, and a day-end step that closes a lapsed card once its holds are gone — the virtual per-purpose card.
- The corporate administrator’s card operations in the client channel, bounded by the entitlement’s ceiling.
- The declining rule on the receipt, so whoever explains a decline can name the rule.
Out of scope:
- The pre-loaded corporate shape (a sub-balance per card): it leaves money idle, and an account per card already models it as configuration.
- Retail cardholder self-service. No retail channel exists; the client channel serves agreements (ADR-693).
- Expense management — receipts, approvals of spend, accounting export (proposal §3.3).
- Moving hold expiry onto category groups. It is a named refactoring opportunity (Notes), not this ADR’s work.
- Merchant-level allow and block lists by merchant identifier: the request carries a name, not a stable merchant id, from the issuer’s side.
- A client-channel screen. No screen exists for any channel operation; the administrator’s acts are bus operations here, as every ADR-695 channel operation is, with no HTTP surface; each card event carries the acting identity. The demo is the bank’s viewer, the probe covering the bank’s half.
- Splitting cashback from a purchase, and telling the cardholder a decline’s rule.
Decisions
1. A spend limit is a scope, a period, an amount and a count
A card’s limits are a list. Each limit names:
- a scope: all spend, one channel (ATM, online, in store), or one merchant category group;
- a period: one transaction, the trading day, the calendar month, or the card’s life;
- an amount ceiling, a count ceiling, or both.
The three ceilings of ADR-835 become three limits of scope all spend. A cash limit of 2 000 a day is a limit of scope cash (the category group), period day. A single-use card is a limit of scope all spend, period life, count 1.
The oracle checks every limit whose scope matches the tap. An amount breach declines
CeilingExceeded (ISO 8583 61); a count breach declines FrequencyExceeded (65, the
standard’s “exceeds withdrawal frequency limit”). Spend in a period is ADR-836’s sum over the
card’s holds placed in it, filtered to the scope; the count is the number of those holds, a
fully reversed hold counting for nothing. The day is the trading date, the month its calendar
month, and the life starts at issue and survives a reissue, because a reissue keeps the card.
A limit list is valid when every amount is at least zero, every count at least one, each limit
has an amount or a count, no two limits share a scope and a period, a transaction limit has no
count, and, within one scope, transaction ≤ day ≤ month ≤ life wherever both are set
(CARD_CONTROLS_INVALID, ADR-835’s code).
Ruled at the grill. A limit is in the card’s billing currency, which is every funding account’s (ADR-835 D5), and compares the billing amount. Spend sums every hold placed in the period, in any state, net of reversals only: a cleared, expired or unanswered hold still counts, and expiry is not a reversal, so a single-use card stays used after its hold clears. An incremental authorisation is its own hold (ADR-836) and counts as a tap. Counts order as amounts do: transaction, day, month, life. An unbound period of a scope is free, capped by any longer period’s limit of the same scope and by every all-spend limit. The day stays the trading date (ADR-835 D6, held): a tenant whose day-end walks every calendar day sees calendar days; one that skips weekends sees a weekend share Monday’s limit. Each hold is stamped at placement with the category groups its merchant category matched, and a scoped limit filters on that stamp, so widening a group never re-counts spend already made.
Ruled at phase A. A channel scope is the tap classified as the switches classify it — ATM, in store (card present) or online (card not present) — so a phone wallet in a shop is in store, and mail, telephone and recurring are online. Cross-scope combinations, such as a cash day above the all-spend day, are accepted at edit and bind at the oracle. The stamp is decided by the oracle at placement and travels on the hold-placed event, so a projection rebuild never re-stamps a hold. Spend reads only the card’s own holds, loaded by card after the rules have passed.
Ruled at the plan grill. One classifier decides a tap’s channel for both the switch check and the stamp. One spend computation serves the oracle, the bank’s limit-use read and the corporate view. The oracle fetches the card for writing first and reads its holds in the same unit of work, so two taps racing on one card conflict and the second is decided again against the first one’s hold; a single-use card can never approve twice. A card’s hold documents are kept while it is open: a future retention job skips open cards, or a single-use card would become usable again.
Ruled at phase B. A limit’s use shows, beside the card’s limit, the tightest product bound that caps it at the oracle — its own, a longer period’s, or all spend’s — when that bound is lower or the card has no limit there; a transaction row reports nothing spent.
2. Merchant category groups are a tenant vocabulary
A merchant category group names a set of merchant category codes (ISO 18245) by inclusive ranges: cash, quasi-cash, gambling, airlines, lodging, car hire, fuel, dining, groceries. The groups are tenant settings, seeded from the schemes’ standard groupings, and each row carries a typed id derived from its key (ADR-422, slug-derived). A code may sit in several groups; a group is never empty.
A limit or a rule names a group by its id, so a bank that renames a group’s label changes no card, and a bank that widens a group’s ranges widens every card naming it, which is what the bank meant.
Ruled at the grill. A group’s key is fixed once created; its label and ranges may change. A
group named by a card type’s bounds or by any card’s rule or limit cannot be deleted
(MERCHANT_CATEGORY_GROUP_IN_USE). A merchant category in no group passes a block rule and
fails an allow-only rule, as an absent country does. A settings change takes effect on the next
tap after it is saved: the settings cache is invalidated on save.
Ruled at phase A. A group’s key is its identity: changing a key removes one group and adds another, and the removal is refused while the old group is named by a type’s bounds or default controls, or by an open card. Closed cards do not count. The template seeds nine groups with the schemes’ standard ranges (the plan lists them).
Ruled at the plan grill. The template’s groups and the corporate type’s bounds reach a tenant through the package model, and a test proves the seeded corporate type blocks gambling and bounds a month, since a key the importer does not know is dropped without a word.
Ruled at phase B. A malformed group key is refused naming the key
(MERCHANT_CATEGORY_GROUP_KEY_INVALID), never a server error. A group is in use while any card
not yet closed names it, a lost or stolen card included.
3. Category and country rules allow only, or block
A card carries an optional category rule and an optional country rule. Each is a mode — allow only or block — and a list: group ids for categories, ISO 3166 codes for countries.
Both apply to every tap, online included, against the merchant’s category and the merchant’s
country. They are not the domestic-country check of ADR-836, which asks whether the card was
present abroad and stays as it is. A merchant country the request does not carry passes a
block rule and fails an allow-only rule, because an allow-only rule is a promise about where the
money may go. Declines: MerchantCategoryNotAllowed (57) and ADR-836’s CountryNotAllowed
(57).
The oracle’s order puts the rules before the limits (the full order is in the ruling below), so the cheaper answer comes first and a blocked tap never reads spend.
Ruled at the grill. The order is total, and the first failure names the rule: token, status,
valid-until, credential, currency, channel, then the type’s always-blocked groups, the card’s
category rule, the domestic-country check, the card’s country rule, then limits by period
(transaction, day, month, life) and within a period by scope (all spend, channel, category),
amount before count. A card with an allow-only country rule skips the domestic-country
check: the allow list is the stronger statement of where the card may be used, and on a
corporate card nobody else could open a travel window. A block rule leaves the domestic check
in place. An allow-only category rule may not name a group the type always blocks
(CARD_CONTROLS_OUT_OF_BOUNDS). Cashback is not split out: the request carries no cashback
amount (ADR-820), so a cashback tap is judged by its merchant category.
Ruled at phase A. Among category scopes in one period, the tenant’s group order decides which rule is named. A merchant country the request leaves empty is absent. The declining rule is written in invariant figures with a plain space between thousands, and names a group by its key, never its label, so renaming a label never changes a stored receipt.
Ruled at phase B. An allow-only rule names at least one group or country; a card that may be used nowhere is a suspended card.
4. The card type carries the bank’s bounds, and every editor works inside them
A card type gains bounds: the highest amount and count allowed for each scope and period,
and the category groups always blocked on that type. Every limit set on a card of the type, by
anyone, must sit within the bound for its scope and period (CARD_CONTROLS_OUT_OF_BOUNDS). An
always-blocked group is blocked by the oracle whatever the card’s own rule says, so a bank that
adds gambling to a corporate type blocks it on every existing card that day.
This is the generic answer to “within what the bank allows” (model page, Who may do what): the product’s limits are the type’s, a configuration change; the customer’s limits are the card’s.
The oracle now reads two cached settings documents beside the card summary — the category groups and the card type’s bounds. That widens ADR-836 D9’s “one document” by two cached reads, and no stream.
Ruled at the grill. The oracle applies the type’s bounds as limits, so lowering a product’s
bound takes effect on every existing card that day, as an always-blocked group does; the
effective limit is the lower of the card’s and the bound. A card limit above a lowered bound is
not rewritten: the editor shows it flagged above the product’s bound. At edit time a limit is
checked against the bounds only where the edit adds or raises it, so a clerk or administrator
can still change a card’s countries after the bank tightens the product. Who may issue from the
client channel is the type’s configuration, IssuableFromChannel; such a type must bound an
all-spend month, so every channel card has a finite monthly exposure.
Ruled at phase A. At edit, a limit an edit adds or raises is refused above any bound that would cap it at the oracle — its scope’s bound for its period or a longer one, or an all-spend bound for its period or a longer one. Removing a limit is never raising. A category rule is refused only when the edit adds an always-blocked group to an allow-only list. A type’s default controls are validated against its own bounds.
Ruled at phase B. A type’s own faults — a duplicate scope and period, a negative amount, a
count on a transaction bound, a group the tenant does not define — are CARD_TYPE_BOUNDS_INVALID.
A channel-issuable type’s month bound must carry an amount. Lowering a limit that is still above
a lowered bound is accepted, because it raises nothing.
5. A card may be valid until a date, and lapses then
A card gains an optional valid-until date, set at issue or later, never in the past. After
it, the oracle declines CardLapsed (54, “expired card”). Holds already placed clear as usual.
CloseLapsedCardsStep, at day-end, closes a card whose valid-until has passed and which has no
open hold, so a lapsed card leaves the books without releasing a hold a merchant may still
clear. A virtual per-purpose card is then a virtual credential, a life limit and a valid-until:
no new aggregate, no new card kind.
Ruled at the grill. Valid-until is inclusive and compared with the trading date; a card valid
until 30 November declines from 1 December and closes at that day-end once its holds are gone.
The decline is its own reason, CardLapsed (ISO 8583 54), with the rule text “valid until
2026-11-30, lapsed”, so a receipt never blames a credential that is fine. Valid-until may be
moved later while the card is open, which revives a lapsed card not yet closed.
Ruled at phase A. Valid-until may be cleared or moved earlier as well as later, never before the trading date, on a live card — ordered, active or suspended — as setting controls is. The day-end whose clearing or expiry frees a lapsed card’s last hold closes it, at step 46 after both.
Ruled at phase B. A lapsed card closes from any status short of closed, a bank suspension and a lost card included: closing is stricter than either. Reviving a lapsed card makes it no longer lapsed and nothing more, so a spent single-use card stays spent. Valid-until is compared with the trading date, never the request’s own date.
6. The corporate card is configuration; its administrator acts through the client channel
A corporate card is a card type with CardholderMayDifferFromOwner set and a single-account
funding shape naming the corporate’s pooled account. Just-in-time funding is ADR-836’s walk with
one entry; the administrator’s ceiling caps the card’s monthly exposure (below).
The corporate administrator is an ADR-695 channel user holding an entitlement over the
corporate card operations, scoped to the pooled account. Operations join ChannelCatalog (eight, since phase A),
each with a pinned key, each asserting against the funding account it names:
- issue a corporate card to a named cardholder, on a corporate card type, funded by that account;
- set a card’s controls;
- suspend, reinstate and close a card.
Each names the funding account explicitly, and the handler refuses unless it is the card’s
funding rule (CORPORATE_CARD_ACCOUNT_MISMATCH). They dispatch to the card’s existing verbs, so
the card cannot tell a bank clerk’s change from an administrator’s, except by who made it.
The entitlement’s ceiling bounds what an administrator may grant. Under ADR-695 D11 a
ceiling is an amount and a currency above which an operation is refused. Each channel command
implements IChannelOperation and asserts the funding account with an amount: on issue and
set, the card’s monthly exposure (the ruling below). The channel gate already compares that
amount with the entitlement’s ceiling, in the account’s currency, and refuses above it or on a
mismatch. A corporate’s signing officers can let a team lead grant 5 000 a month and no more,
with nothing new built.
Two reads join the catalog, narrowing to the account scope: the corporate’s cards, and one card with each limit’s spend and count used in its current period.
On a corporate card the named cardholder changes nothing. Controls belong to whoever owns the money. A retail cardholder’s self-service waits for a retail channel (Scope).
Ruled at the grill. The asserted amount is the card’s monthly exposure: the lowest of its
all-spend month limit, its all-spend day limit times 31 and its all-spend life limit (the type’s
bound was struck at the plan grill). So the ceiling caps what one card can spend in a month, per card, and a
corporate’s total is bounded by its pooled account. An administrator may only leave a card
within their own ceiling: an edit that keeps a bank-set limit above it is refused, and the
editor says so. A suspension records who made it — the bank or the client channel — and the
channel may reinstate only its own; a bank’s fraud hold stays until the bank lifts it. A sixth
operation, reveal, opens the processor’s hosted view of a virtual card’s details for the
administrator, so a supplier card can be handed over without card data touching the ledger
(ADR-835’s reveal). The channel’s set replaces the whole list; valid-until has its own
operation (phase A). The owner of a channel-issued card is the funding account’s single owner;
a virtual supplier card’s cardholder is its purpose, embossed (“ACME SUPPLIER CARD”), with no
counterparty. Unlicensing cards.corporate removes the channel operations and the reads; the
cards keep working and the bank still manages them, because taps are not a corporate feature.
Ruled at phase A. The monthly exposure takes the lowest of the card’s and the type’s all-spend
month, day times 31 and life. The channel reaches only cards of a type issuable from the channel
whose whole funding rule is the account named; out of scope, a read returns nothing rather than
refusing. A channel command needs a channel caller (CORPORATE_CARD_CHANNEL_ONLY): the bank
uses its own commands. Two operations join: set valid-until, separate from set controls so
an edit to a supplier card’s countries can never clear its date, and activate, so a plastic
corporate card ordered from the channel can be switched on when it arrives. Every channel change
is mirrored to the processor, as the bank’s are. The bank reads each limit’s use through its
own query, and the corporate view reuses that computation, so the two cannot drift.
Ruled at the plan grill. The asserted exposure is the card’s own: the lowest of its
all-spend month, day times 31 and life. The type’s bounds live in settings, which an operation’s
scope cannot read; the card’s own figure is never below the effective one, so the cost is a
refusal, never a leak. A channel issue or set with none of the three is refused
(CORPORATE_CARD_EXPOSURE_UNBOUNDED), so every channel card states a monthly figure the ceiling
can judge. The channel caller is known from the channel user directory, and the owner is the
funding account’s single owner. The reads assert the funding account, so an account outside the
entitlement is refused and a card outside it reads empty. Every channel operation is a bus
operation, as ADR-695’s are. Suspend and close are run-down and stay available when
cards.corporate lapses, and suspend is never held for a second approval: a stolen card waits
for no one. The corporate view carries the card’s recent authorisations, each with its declining
rule, so the administrator reads why a tap was refused.
Ruled at phase B. A count-only month states no monthly figure and is refused as unbounded. A
card of a type the channel cannot issue is refused CARD_TYPE_NOT_CHANNEL_ISSUABLE, whatever the
operation. Bank-issued cards of a channel-issuable type on the account are in the administrator’s
reach. Unlicensed, the two reads are refused, not emptied. Reinstating clears who suspended.
7. The receipt names the rule that declined
The authorisation receipt gains the declining rule, a short text naming it: “daily, all spend, 5 000.00”, “category gambling, blocked by the card type”, “country US, not in the allow list”. The processor sees only the reason code; the bank’s clerk and the corporate administrator read the rule. A declined cardholder must be told which rule said no, because that decides who can change it (model page, Controls).
Ruled at the grill. The people who can change the rule can read it: the bank’s clerk and the corporate administrator. The cardholder hears it from them; telling the cardholder directly waits for a notification channel.
Ruled at the plan grill. The bank reads a card’s authorisations through a per-card read, and the processor-receipts list gains the rule; the administrator reads them on the corporate view.
8. Permissions, feature and four-eyes
Spend controls ride cards.issuing. Corporate cards are their own feature, cards.corporate,
so a bank can license them separately: it gates the eight channel operations and the two
channel reads. Settings: cards.amend-merchant-category-groups,
cards.view-merchant-category-groups, four-eyes eligible as every settings command is.
CloseLapsedCardsCommand is system-internal. The channel operations are exempt from four-eyes
until client approval rules ship (ADR-695 D13).
Ruled at phase A. cards.corporate gates the channel operations and reads only (suspend and
close excepted, as run-down); the bank may
issue and manage a card of any type whether or not the feature is licensed.
Contracts
Ids — MerchantCategoryGroupId (LedgerTM.Contracts/Cards).
Commands — AmendMerchantCategoryGroupsCommand (ISettingsCommand<MerchantCategoryGroupsSettings>);
SetCardValidUntilCommand (ICommand); CloseLapsedCardsCommand (ISystemCommand); the
channel’s IssueCorporateCardCommand, SetCorporateCardControlsCommand,
SuspendCorporateCardCommand, ReinstateCorporateCardCommand, CloseCorporateCardCommand,
RevealCorporateCardCommand, SetCorporateCardValidUntilCommand, ActivateCorporateCardCommand (ICommand, catalogued with pinned keys).
Events — CardValidUntilSet.
Queries — GetMerchantCategoryGroupsQuery, ListCorporateCardsQuery,
GetCorporateCardQuery, GetCardLimitUseQuery, ListCardAuthorisationsQuery (IQuery<T>).
Consumed from LedgerTM.Contracts — IAvailableBalanceReductionsReader and the card hold
documents (ADR-836); IChannelOperation and ChannelScope.Asserts (ADR-695), which the eight
channel commands implement. The client channel’s operation catalog, in its own project, gains
ten rows by key string, so no project reference is added.
Changed — CardControls loses its three ceilings and gains Limits, Categories and
Countries, with the new value types CardSpendLimit, CardSpendScope, CardSpendPeriod,
CardRuleMode, CardCategoryRule, CardCountryRule, CardSpendChannel, CardLimitUse and
CardAuthorisationLine (LedgerTM.Contracts/Cards); CardAuthorisationDecision gains DeclinedRule; CardSummary gains
ValidUntil and SuspendedBy; CardHoldPlaced gains the channel and the category groups;
CardDeclineReason gains MerchantCategoryNotAllowed, FrequencyExceeded and CardLapsed;
CardSuspended gains By (a new CardActor: Bank, ClientChannel); CardHold, the card hold
document (ADR-836), gains the channel and the category groups its merchant category matched; CardType gains
IssuableFromChannel;
CardAuthorisationReceipt gains DeclinedRule; CardType gains Bounds (CardControlBounds);
CardIssued and IssueCardCommand gain ValidUntil; CardControlsSet carries the new shape;
FeatureCatalog gains cards.corporate.
Removed — CardControls.PerTransactionCeiling, DailyCeiling, MonthlyCeiling (become
limits).
Prior art
| Declared | Search returned | Verdict |
|---|---|---|
CardSpendLimit, CardSpendScope, CardSpendPeriod |
CardControls’ three ceilings (ADR-835 D6), ADR-695’s entitlement ceiling |
extend — the three ceilings are three instances of one concept; the entitlement ceiling is a capability bound on an operation, a different question (ADR-695 D11) |
MerchantCategoryGroupId, MerchantCategoryGroupsSettings, AmendMerchantCategoryGroupsCommand, GetMerchantCategoryGroupsQuery |
CardHoldExpiryRule’s MCC ranges (ADR-836), MerchantCategoryCode (ADR-820) |
genuinely new — the first named grouping; hold expiry’s ranges are the same shape and are named a refactoring opportunity |
CardRuleMode, CardCategoryRule, CardCountryRule, CardSpendChannel |
CardTravelWindow (ADR-835), IsoCountryCode (ADR-386) |
genuinely new — the travel window widens a presence check for dates; these restrict where money goes |
CardActor |
CardSuspended (ADR-835), ADR-695’s channel identity |
genuinely new — who suspended decides who may reinstate |
CardControlBounds, IssuableFromChannel |
CardType.DefaultControls (ADR-835) |
extend — defaults say where a card starts; bounds say how far it may go |
SetCardValidUntilCommand, CardValidUntilSet, CloseLapsedCardsCommand |
CardExpiry on the credential (ADR-835), CardHoldExpiryStep (ADR-836) |
genuinely new — a credential’s expiry is the scheme’s; a card’s validity is the customer’s |
IssueCorporateCardCommand, SetCorporateCardControlsCommand, SuspendCorporateCardCommand, ReinstateCorporateCardCommand, CloseCorporateCardCommand, RevealCorporateCardCommand, SetCorporateCardValidUntilCommand, ActivateCorporateCardCommand |
IssueCardCommand, SetCardControlsCommand, SuspendCardCommand, ReinstateCardCommand, CloseCardCommand (ADR-835) |
extend — channel commands naming the funding account the gate asserts against, dispatching to the same verbs; duplication over a scope resolver the channel gate does not have |
ListCorporateCardsQuery, GetCorporateCardQuery, GetCardLimitUseQuery, CardLimitUse, ListCardAuthorisationsQuery, CardAuthorisationLine |
ListCardsQuery, GetCardQuery (ADR-835) |
extend — narrowed to the channel scope, with spend used |
MerchantCategoryNotAllowed, FrequencyExceeded, CardLapsed |
CardDeclineReason’s control reasons (ADR-836), MerchantCategoryCode (ADR-820) |
extend — two more causes, each its own ISO 8583 code, as ADR-836 split ControlBreached |
CardAuthorisationDecision, CardHoldPlaced, CardSummary |
the seams as ADR-835 and ADR-836 left them | reuse — extended by trailing members |
CardDeclineReason, CardAuthorisationReceipt, CardControls, CardType, CardIssued, IssueCardCommand, CardControlsSet |
the seams as they are | reuse — extended by members |
Relies on
| Symbol | What it does today | What this ADR assumes |
|---|---|---|
CardControlsRule.Faults |
per-transaction ≤ daily ≤ monthly, none negative (ADR-835’s IsValid) |
generalised per scope over the limit list |
Card.SetControls |
records CardControlsSet |
carries the new shape unchanged as a verb |
CardType.CardholderMayDifferFromOwner |
lets a named cardholder differ from the owner | a corporate card type sets it |
Worked example
Fixture: the retail-bank template; Acme Engineering (Pty) Ltd, a corporate client under a channel agreement, holding a pooled ZAR current account with 250 000.00 available; Thandi, a channel user with an entitlement over the corporate card operations on that account, ceiling ZAR 25 000.00; the corporate card type bounding a month at 50 000.00 and always blocking gambling. Trading date Mon 2026-11-02.
| Step | Act | Result |
|---|---|---|
| 1 | Thandi issues J SMITH a card: 2 000.00 a transaction, 5 000.00 a day, 20 000.00 a month; categories block cash; countries allow ZA and GB | Issued, funded by the pooled account |
| 2 | Thandi raises the month to 30 000.00 | Refused: above her entitlement’s 25 000.00 |
| 3 | A 1 500.00 grocery tap in ZA | Approved; hold on the pooled account |
| 4 | A 2 500.00 tap in ZA | Declined CeilingExceeded; rule “transaction, all spend, 2 000.00” |
| 5 | A 100.00 online casino (7995) | Declined MerchantCategoryNotAllowed; rule “category gambling, blocked by the card type” |
| 6 | An 800.00 ZAR online purchase from a GB merchant | Approved |
| 7 | A 300.00 online purchase from a US merchant | Declined CountryNotAllowed; rule “country US, not in the allow list” |
| 8 | Thandi issues a virtual supplier card: life 12 000.00, count 1, valid until 2026-11-30 | Issued, active at once |
| 9 | 11 500.00 to the supplier; then 100.00 | Approved; then declined FrequencyExceeded |
| 10 | Day-end of 2026-12-01, the supplier’s hold cleared | The virtual card is closed |
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 Bounds {
<<new>>
}
class CardLapsed {
<<new>>
}
class Categories {
<<new>>
}
class ClientChannel {
<<new>>
}
class Countries {
<<new>>
}
class DailyCeiling {
<<new>>
}
class DeclinedRule {
<<new>>
}
class FrequencyExceeded {
<<new>>
}
class IssuableFromChannel {
<<new>>
}
class Limits {
<<new>>
}
class MerchantCategoryNotAllowed {
<<new>>
}
class MonthlyCeiling {
<<new>>
}
class SuspendedBy {
<<new>>
}
class ValidUntil {
<<new>>
}
class Card {
<<relies-on>>
}
class CardControlsRule {
<<relies-on>>
}
class CardType {
<<relies-on>>
}
Consequences
Positive
- The corporate expense card is sellable with nothing but configuration and eight channel operations; a demo is: issue a card in the channel, tap, see a decline name its rule.
- One limit concept answers every ceiling a prospect asks for — cash per day, travel per trip, single use — without a new field each time.
- A bank adds a blocked category to a product once, and every card of it obeys that day.
Negative / Trade-offs
CardControlschanges shape under a shipped ADR and an in-flight one: ADR-835’s controls editor and ADR-836’s ceiling check are rewritten, and the change is a reseed.- The oracle reads two more cached documents per tap.
- Eight channel commands duplicate bank commands, because the channel gate asserts against named accounts and a card command names none.
Neutral
- Hold expiry keeps its own ranges until the refactoring in Notes is scheduled.
Implementation Plan (Bites)
Five bites, one land; reseed: true. Every bite starts after ADR-836 lands.
Bites, acceptance criteria, files touched, and status live in ADR-844-plan.md.
Changed during the grill
Grilled 2026-10-02 by the author against ADR-695, ADR-835 and ADR-836; the operator’s standing instruction was to take the recommendations. What changed:
- Decision 1 — limits in the billing currency; spend counts every hold placed, net of reversals only, so a single-use card stays used; holds stamped with their groups, so widening a group never re-counts the past; the cash limit is the cash group, not the ATM channel.
- Decision 2 — a group’s key is fixed and a group in use cannot be deleted, so a rename can no longer silently lapse a block.
- Decision 3 — one total order of checks, so one rule is named; an allow-only country rule replaces the domestic-country check, which nobody on a corporate card could otherwise open.
- Decision 4 — the type’s bounds bind at the oracle as well as at the edit; a channel-issuable type must bound a month.
- Decision 5 —
CardLapsedin place ofCredentialExpired; valid-until is inclusive. - Decision 6 — the ceiling asserts the card’s monthly exposure, closing a hole where a card with only a day limit could spend thirty times the ceiling; a bank’s suspension cannot be lifted from the channel; a reveal operation so a supplier card can be handed over.
- Decision 7 — the rule is read by whoever can change it.
- Pressed and held — the trading date as the day (ADR-835 D6); five channel commands duplicating the bank’s, over a scope resolver the channel gate does not have.
Contradiction press: 15 pairs, resolved as above — 1 and 11 into Decision 6 and 4’s exposure and bounds; 2 into Decision 4; 3, 7, 9 and 15 into Decision 1; 4 into Decision 2; 5 into Decision 6; 6 into Decision 1 and Scope; 8 and 12 into Decision 3; 10 into Decision 4; 13 into Decision 7; 14 into Decision 5. The nine gaps are answered in the same paragraphs.
The press, as returned
Contradiction press: 15 pairs (condensed)
- D6’s ceiling asserted the largest limit amount, not a period, while claiming “5 000 a month”: a day-only card could spend about 155 000 a month.
- D4’s bounds bound edits but not taps, while always-blocked groups bound taps.
- Whether a cleared or expired hold still counts: a single-use card could be used twice.
- Renaming or deleting a group’s key orphaned every rule naming it.
- The administrator could reinstate a card the bank suspended for fraud.
- Cash had two mechanisms (ATM channel, cash group), and cashback escaped both.
- Limits had no currency; an 800.00 GBP tap against a 2 000 limit.
- A country allow list said yes, the domestic check said no, and nobody could open a travel window.
- The trading date as the day stretched day limits over weekends and moved month and valid-until edges.
- The ceiling and bounds refused edits that raised nothing.
- A scope or period the type did not bound: free or forbidden?
- One declining rule, but several rules could decline one tap; the type’s block had no slot in the order.
- “The cardholder must be told” with no channel to tell them.
- A lapsed card declined as an expired credential; which day-end closes it.
- Widening a group re-counted spend already made.
Gaps: incremental authorisations; a category in no group; changing valid-until after issue; when a settings change takes effect; unlicensing cards.corporate; count ordering across periods; a virtual card’s cardholder; an allow-only rule naming an always-blocked group; a count-only card’s asserted ceiling.
Phase A (acceptance-test author, 24 questions), 2026-10-02. The rulings that changed a decision are the “Ruled at phase A” paragraphs of Decisions 1 to 6 and 8. In short: the channel scope is the tap’s classified channel; the stamp travels on the event; a group’s key is its identity; the declining rule’s text is fixed per rule; bounds at edit mirror the oracle; valid-until can be cleared and has its own channel operation; activate joins the channel; the exposure includes the type’s day and life bounds; the bank reads limit use through its own query.
Changed during the plan grill
An Opus plan grill pressed every signature on 2026-10-03 and returned 18 points; all were taken on its recommendations, the operator’s standing instruction. Those that changed a decision:
- Decision 6 — the exposure is the card’s own. An operation’s scope cannot read settings, so the draft’s “the type’s bounds too” let a card with no limits of its own pass a 25 000.00 ceiling and spend 50 000.00. A channel card must now state a monthly figure.
- Decision 1 — the oracle locks the card before reading its spend, so two simultaneous taps cannot both pass a single-use or count limit; one spend computation serves every reader.
- Decision 2 — the seed reaches the tenant, proved by a test; the importer would have dropped the corporate type’s bounds silently.
- Decision 6 — channel operations are bus-only, reads assert the account, suspend and close outlive the licence, suspend is never held for approval.
- Decision 7 — the rule has a surface: a per-card authorisation read for the bank and recent authorisations on the corporate view.
- Plan only — bite 1 carries every file the controls’ new shape breaks; the step is registered; the menu gains set valid-until; every handler and endpoint has a dispatching test.
Changed during phase B
Five acceptance-test authors wrote the cold tests on 2026-10-03 (docs/adr/ADR-844-tests/). Their
findings are folded as the “Ruled at phase B” paragraphs of Decisions 1 to 6:
- Decision 1 — a limit’s use shows the tightest bound that caps it; spend sums the hold’s approved billing amount, never the merchant’s currency; a limit breach is final, with no partial approval up to the remainder; a bound equal to the card’s limit names the card’s.
- Decision 2 — a malformed key has its own refusal; a lost card still holds a group in use.
- Decision 3 — an allow-only rule names at least one entry.
- Decision 4 — the type’s own faults share one code; a channel type’s month bound carries an amount.
- Decision 5 — setting valid-until is a live verb, as setting controls is; a lapsed card closes from any status short of closed; reviving restores nothing else.
- Decision 6 — a count-only month is unbounded; the stale grill text on the exposure, the owner and valid-until is struck.
Notes
- Refactoring opportunity, worth a session: hold expiry (ADR-836 D7) names merchant categories by its own ranges. Repointing its rules at category groups leaves one grouping, so a bank widening lodging also widens the thirty-day hold.
- Depends on ADR-836 (the oracle, the holds, the reductions) landing first; this ADR rewrites its ceiling check. ADR-695’s channel gate and catalog are shipped.
- Standards: ISO 18245 for merchant categories, ISO 3166 for countries, ISO 8583 for the response codes (51, 54, 57, 61, 65); the register’s ISO 8583 row gains code 65.
- Spend limits on the price list: a limit is a natural price-list axis (a premium card type bounding higher); flagged, not built.
Outcome
Landed as designed in five bites, with one decline path and one read path for all eight rules. Bite 1 also had to declare the later bites’ contract types so the authored tests compiled. The bite-4 tests were re-authored twice, once for an ADR-807 signature and once for an assertion that compared nothing. The inbound mapper now reads an empty merchant country as absent.