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-841: Cards and Authorisation: the attribute-banded price card
Status: Shipped — 2026-10-04
Context
The Problem
A card fee is never one number. The same bank charges a different ATM fee at home and abroad, a foreign-currency markup only when the merchant billed in another currency, nothing to replace a credit card and 150 to replace a debit card, and a cash-advance fee that depends on where the cash came from. Every incumbent core prices this as a custom build; every prospect asks for it in the first demo.
The platform prices by one number today. A price row is (type, effective date, value)
(ADR-419) on a price list an account’s pricing plan names, read by price('x', valueDate). The
card ADRs so far have priced flat: ADR-839’s three fees, ADR-838’s annual, late-payment and
cash-advance fees, ADR-840’s case fee. ADR-838 and ADR-839 both deferred “fees that vary by
scheme, region, channel or amount” to this ADR.
What Already Exists
PriceSettings(ADR-419): price types as tenant vocabulary with a typed id (ADR-422), kindAmountorRate, price lists holding dated rows, the lookup “latest effective row at or before the value date” (PriceList.GetPrice).PricingPlanper account: a price list plus per-account overrides and percentage adjustments applied after the list’s answer.IPriceProvider/IPriceProviderResolverin Contracts: the seam every feature prices through; the external-source dispatcher binds it for a card fee (ADR-839 F5) andprice()in a workflow reads it.- The banded rate card (ADR-250):
RateBand(term, fromAmount, toAmount)holding a dated rate series, matched by term and amount, soft-closed. The shape this ADR generalises — a price chosen by selectors and an amount band, carrying a dated series. - The clearing line and the authorisation request (ADR-820, ADR-836) carry every attribute a card price turns on: channel, entry mode, merchant country, original currency, DCC, merchant category. ADR-836’s purchase posting carries the merchant as properties; the card’s type and scheme are the card’s.
- ADR-416’s rail fee: a rail names a price key; the fee is what the key resolves to on the paying account’s plan. A rail fee that differs by urgency or amount is the same problem.
Scope
This ADR covers:
- The price row gaining selectors (attribute = value) and an amount band, and the lookup
choosing the most specific matching row — the attribute-banded price, in
LedgerTM.Pricing. - The price type declaring which selector keys its rows may use, and the settings UI showing a type’s rows as a matrix.
price(type, valueDate, amount)in the scripting engine, and the pricing attributes a dispatcher binds for the lookup to match against.- The card attributes — scheme, card type, channel, entry mode, cross-border, currency conversion, original currency, DCC — supplied by Cards on every purchase posting, and the retail template’s card fees priced by them: the currency-conversion fee, the ATM fee, the cash-advance fee cross-border, the replacement fee by card type.
CardType.Scheme.
Out of scope: per-merchant pricing plans and interchange (the merchant settlement ADR, which uses this shape with merchant selectors); a fee-inclusive authorisation hold (the hold stays the billing amount; a fee posts at clearing and may push a deposit account into ADR-837’s excess, as it does at every bank); interchange and scheme fees the bank pays (the acquiring side); refunding a fee charged on a line later refunded, reversed or disputed (the fee stands, as the industry has it; ADR-840’s credit is the disputed amount); per-band or per-selector overrides on a pricing plan; a per-card annual fee by card type (ADR-838’s annual fee is the account’s, scheduled on the account, where no card attribute is known — a card-level annual fee is a Cards-dispatched fee, a later item); ADR-416’s rail fee gaining the bag (when a tenant asks; the shape serves it unchanged).
Decisions
1. A price row carries selectors and an amount band; the most specific row wins
Price gains Selectors — a small map of attribute key to value, both kebab-case strings,
lower-case, matched exactly — and an optional band FromAmount/ToAmount, inclusive at the
bottom and exclusive at the top, ToAmount null for an open top (“2% above 500” is a band from
500 with no top). That deviates from ADR-250’s inclusive rate bands, deliberately: adjacent
price bands must not meet, and a fee band needs an open top. A Rate row also gains an
optional floor and cap, Minimum and Maximum, amounts in the list’s currency, dated with the
row. A row with no selectors and no band is what every row is today, so nothing seeded changes
meaning. A row’s value may be 0: a waived fee is a price of zero (ADR-416), and the validator’s
> 0 becomes >= 0.
The lookup for a type on a list, given a value date, a pricing context (attributes and an
optional amount), is: every row of the type effective at or before the date, whose selectors
all match the context’s attributes, and whose band (if any) contains the amount; among them the
row with the highest specificity — its selector count, plus one if it carries a band; among
those the latest effective date. A row naming an attribute the context does not carry does
not match, a banded row does not match a context with no amount, so the unselected unbanded
row is the fallback. A type that declares selectors must carry that fallback on every list that
prices it (PRICE_FALLBACK_REQUIRED: the type’s earliest fallback row is on or before its
earliest selected or banded row, checked over the whole list after every change and once per
list after an import, whatever order the rows are entered), so a lookup with attributes can
never miss where the plain lookup hits; a miss is then what it is today — the type is unpriced on that list and
date, and price() refuses as ADR-704 has it. Rows
with the same selector set and band are one dated series, as a type’s rows are one series
today, so a dated change to the cross-border ATM fee is a new row in that series. A series is
retired by a dated row marked Retired: from that date the lookup treats the series as absent
and falls through to the next most specific row — a row of 0 would waive the fee, not retire
the series; the fallback series cannot be retired while a selected row stands. Rows are also removed one by one as today, which changes back-dated answers.
A change to a row that exists — same series, same date — replaces it; it is an edit, never a
duplicate. Two rows of different series that both match one context are not an error when
their specificity differs — the higher wins — but two of equal specificity that could both
match are a tie, and a tie is refused at the settings command: every pair of rows of one type
with equal specificity, selector sets that disagree on no shared key, and bands that overlap
(an unbanded row overlaps every band; a row with no band and no selectors is the fallback and
never ties; two rows of one series never tie), whatever their dates. The checks live on
PriceSettings itself, so the importer meets them as the settings command does; a refusal is a
domain error naming the type, the selectors, the band and the date of each row. The settings UI
never lets a tie be entered.
2. A price type declares its selector keys
PriceTypeEntry gains Selectors, one entry per attribute key its rows may name, each with the
values it allows — ADR-700’s MetricDimension shape, which exists for exactly this failure: a
row typed foriegn would otherwise never match and every cross-border withdrawal would charge
the domestic fee with nobody told. A row naming a key the type does not declare, or a value the
key does not allow, is refused. The keys and values are free kebab-case, a tenant’s own
vocabulary — cross-border, channel, card-type, scheme, rail, urgency — and the
settings matrix shows a column per declared key with a picker over its values. A type with no selectors and no banded row
is a flat price, as every type is today; a type with no selectors may still band by amount,
and the matrix shows a band column when any row has one. A selector value naming a currency
carries its ISO 4217 code lower-case (usd), since values are kebab-case.
3. The lookup takes a pricing context, bound by whoever dispatches the posting
IPriceProvider gains GetPrice(string priceType, DateOnly valueDate, PriceContext context),
its TryGetPrice twin, and Quote/TryQuote — the chosen row’s value, kind, floor, cap and
the list currency’s minor unit, as a PriceQuote that computes its own fee — where
PriceContext(IReadOnlyDictionary<string, string> Attributes, decimal? Amount); the
two-argument forms are the empty context. The pricing plan’s overrides and adjustments apply
after the row is chosen, to its value, as they do today — and never to a zero-valued row: an
override of card-currency-conversion-fee overrides the conversion row and leaves the waived
fallback at 0, which is what “this customer pays 1% abroad” means; a Rate row’s floor and cap
stay as the row has them; an override with no matching row is nothing, as today; an override on
a type whose list has no positive row of any series on that date is refused
(PRICE_OVERRIDE_ON_WAIVED), so
“charge this customer 50 for renewal” over a waived renewal fee is told no rather than silently
ignored; an override on a Rate type is entered as a rate and refused above 1. The override now
applies from its own effective date (F-1796, fixed here: PriceAdjustment carries the date its
event already has).
A workflow reads price(type, valueDate) as today and, new, price(type, valueDate, amount)
for a banded price — still the dumb decimal ADR-419 made it — and fee(type, valueDate, amount),
the fee the row computes: an Amount row’s value; a Rate row’s rate times the amount, floored
at the row’s Minimum, capped at its Maximum, rounded half-up to the list currency’s minor
unit (the list’s currency as the tenant’s currency settings record it, resolved once when the
provider is built; 2 where unset).
The formula lives on PriceQuote in Contracts, beside the row that defines it; the scripting
engine only calls it. The rate applies to the whole
amount, never marginally. A rate of zero, a waived or fully discounted value, or an amount of
zero or less gives a fee of zero, an Amount row included: the floor lifts a charge, never
creates one. The attributes are not script
arguments: the external-source dispatcher
binds the posting’s pricing attributes into the evaluation context, and price() matches
against them. The purchase and card-fee commands (ProcessCardPurchaseCommand,
ProcessCardFeeCommand; Decision 4 says why no other) gain
PricingAttributes: IReadOnlyDictionary<string, string> — a bag, filled by whoever knows the
facts, passed through by Accounts, recorded on TransactionPosted.Properties under a
pricing. prefix, kebab as the bag has it (pricing.card-type), on every leg of the dispatch,
so the auditor can see which attributes priced the fee. Each attribute is
also a $ parameter of the workflow, its key camel-cased ($cardType, $entryMode); the
parameter names are the eight card keys, declared on the card sources in the template
validator, bound to the empty string where the bag has no value, so every script compiles and
$channel == 'atm' is simply false on a posting with no bag. A tenant’s own selector keys
reach a script only through price() matching, never as parameters. An operation’s own
declared input of the same name is refused by the type validator. Script
arguments would have made every workflow restate the attribute list; a bag the dispatcher binds
means a tenant adds a selector to a price type and a value to the bag without touching a
script.
4. Cards supplies eight attributes on a purchase posting, two on a fee of its own
| Key | Values | From |
|---|---|---|
scheme |
the card type’s scheme key (visa, mastercard, …) |
CardType.Scheme, new |
card-type |
the card type key | the card |
channel |
card-present, ecommerce, mail-or-telephone, recurring, atm, wallet |
CardChannel; atm also when the merchant category is 6011, so one fact says ATM wherever a tenant branches on it (ADR-838 branches its cash advance on 6010/6011: counter cash, 6010, is a cash advance on a credit card and no ATM fee on a debit card) |
entry-mode |
chip, contactless, magnetic-stripe, keyed, token, unknown |
CardEntryMode |
cross-border |
yes, no |
the line’s merchant country, parsed as ISO 3166 alpha-2, against CardProcessorSettings.DomesticCountry (ADR-836 F7); a null facet, a blank or unparseable country → no (the bank cannot show the customer was abroad — the opposite of ADR-836’s control check, which reads an unknown country as abroad to decline, deliberately: one parse, two null answers, each on the customer’s safe side); the schemes’ own word for the fee |
currency-conversion |
yes, no |
the line’s original currency against the funding account’s currency; equal, or a DCC line, → no; the schemes’ own word |
original-currency |
an ISO 4217 code, lower-case | the line’s original currency |
dcc |
yes, no |
the line’s DCC flag; a DCC purchase was billed in the account’s currency by the merchant, so currency-conversion reads no whatever the line’s original currency says, and it pays no markup unless a tenant adds a dcc: yes row |
A fee posted by Cards itself (ADR-839’s issuance, replacement, renewal; ADR-840’s case fee)
carries scheme and card-type only. A refund, a dispute credit and a clawback carry no
bag: their workflows price nothing, and a pricing. property on a credit would read as if it
had; the auditor finds the line’s attributes on the purchase posting ADR-840 already links to.
A fee charged at clearing stands when the line is later refunded, reversed or disputed.
CardType gains Scheme, a kebab-case key the validator requires and storage allows empty
(existing rows carry none until edited; an empty scheme is left out of the bag), seeded visa
on the retail template’s card types and the fixture’s.
5. The retail template prices four card fees by attribute, and the purchase workflow charges two of them
Every clearing line posts as CardPurchase (ADR-836; the credit card branches a cash advance
by merchant category, ADR-838); $amount is the billed amount in the account’s currency.
card-currency-conversion-fee(Rate, selectorscurrency-conversion):{ currency-conversion: yes }0.0275 and a fallback row{}0. On the credit card the row posts Dr Fees, Dr Outstanding withcostOfCreditCategory: Feeand the tax treatment ofCashAdvanceFeeCharged, and sits before ADR-838’s payment allocation so a waiting credit absorbs it. The purchase workflow on every type carryingcardPurchasechargesCardCurrencyConversionFeeCharged fee('card-currency-conversion-fee', valueDate, $amount)underwhenCondition price('card-currency-conversion-fee', valueDate, $amount) > 0— the three-argument form, so the guard reads the same row the fee does — so a domestic purchase, or a bag with nocurrency-conversion, posts no fee row. The fee rows follow the purchase leg in the workflow: a zero fee posts nothing, and a fee leg first would claim the dispatch id for nothing. A foreign ATM withdrawal in a foreign currency pays it beside the ATM fee, as it does at every bank.card-atm-fee(Rate, selectorscross-border): the fallback{}and{ cross-border: no }both 0.02 with a floor of 10 — 10 up to 500, 2% above — and{ cross-border: yes }0.03 with a floor of 60. The deposit types’ purchase workflow chargesCardAtmFeeCharged fee('card-atm-fee', valueDate, $amount)underwhenCondition $channel == 'atm'. The credit card’s workflow does not carry this row: its ATM withdrawal is the cash advance it already charges by merchant category (ADR-838), andcard-cash-advance-feekeeps its flat row as the fallback and gains{ cross-border: yes }100 (selectorcross-border).card-replacement-fee(ADR-839) keeps its flat 150 as the fallback and gains{ card-type: credit }0 — the credit card (ADR-838’screditcard type) is replaced free. ADR-839’sprice('card-replacement-fee', valueDate)call does not change; the dispatcher’s bag now carriescard-type, and the row is chosen. This is the demonstration: a fee that was flat becomes tiered by configuration alone.
The workflow’s $channel, $currencyConversion and the rest are the bag’s values exposed as parameters
(Decision 3), so a whenCondition can branch on them as it branches on $merchantCategory
today.
6. The settings surface is a matrix per type
The price list page shows a type’s rows as a matrix: the fallback as a fixed first row, one
column per declared selector, the band, and the dated value series with its floor and cap; a
new row is entered by picking a value per selector from the values the key allows. A type with
no selectors shows the single column it shows today. The settings aggregate refuses the
undeclared key or value, the malformed key, the bad band, the missing fallback and the tie
(Decision 1) with codes naming the row; the read is GetPriceMatrixQuery under its own key,
pricing.view-price-matrix, in Pricing’s settings route family; it carries the list’s
currency and minor unit, orders the fallback first and the rest by specificity then selector,
answers 404 for an unknown list or type and an empty matrix for a type the list does not price
yet, and reads a deactivated type’s rows.
7. A debit card prices as before
Every row seeded today keeps no selectors and no band and stays the fallback, so every existing
fee prices as before for every card and account that exists; the only new answers are the
credit card’s free replacement, the two new fee types, and the foreign cash-advance row — four
types touched. reseed: true because the row shape and the posting’s properties change, and
the retail template and the fixture gain the rows; [redacted]’s package has no cards and is
untouched.
Contracts
Ids — none new; PriceTypeId, PriceListId as they are.
Commands — ProcessCardPurchaseCommand and ProcessCardFeeCommand gain PricingAttributes
(changed, LedgerTM.Contracts/Accounts); ChangePriceCommand, RemovePriceCommand, AddPriceTypeCommand and
EditPriceTypeCommand (the existing LedgerTM.Pricing settings commands) carry the selectors
and the band;
AmendCardTypesCommand (ADR-835) carries Scheme.
Events — TransactionPosted.Properties gains the pricing. entries (an existing event’s
property bag, no new event).
Queries — the ListPrices endpoint (the existing price-row read) returns the rows with
their selectors, bands, floors and caps (changed); GetPriceMatrixQuery (LedgerTM.Pricing,
IQuery<PriceMatrixView>) answers a type’s matrix for the settings page.
Consumed from LedgerTM.Contracts — IPriceProvider (changed: the context overloads),
IPriceProviderResolver, PriceKind, CardChannel, CardEntryMode.
Consumed from LedgerTM.Pricing — IPriceTypeCatalog, PriceTypeInfo.Selectors. Each lived in Contracts when this ADR shipped, and moved to its only reader on 2026-10-21 (ADR-755 ruling). This ADR changed both: PriceTypeInfo gained Selectors.
Consumed from LedgerTM.Cards — CardClearingItem. Each lived in Contracts when this ADR shipped, and moved to its only reader on 2026-10-21 (ADR-755 ruling).
Changed — PriceContext, PriceQuote and PriceSelectorInfo (new, LedgerTM.Contracts/Pricing/PriceLists);
IPriceProvider gains GetPrice(string, DateOnly, PriceContext), TryGetPrice(string, DateOnly, PriceContext), Quote(string, DateOnly, PriceContext) and TryQuote(string, DateOnly, PriceContext);
PriceAdjustment gains its effective date (F-1796); PriceTypeInfo gains Selectors;
Price gains Selectors, FromAmount, ToAmount, Minimum, Maximum; PriceTypeEntry gains
Selectors with allowed values; CardType gains Scheme; the scripting price() accepts a third amount argument
and fee() is new; WorkflowDispatchContext gains PricingAttributes.
Removed — none.
Prior art
| Declared | Search returned | Verdict |
|---|---|---|
PriceContext |
RateBand.Matches(term, amount, date) (ADR-250), PriceAdjustment.Applies |
genuinely new — the question “which attributes is this price for” has no carrier; the band’s match is term-and-amount only |
PriceQuote, IPriceProvider.Quote/TryQuote, fee() |
price() (ADR-419 D3, a dumb decimal), RateTier |
genuinely new — a row’s floor and cap have no carrier; price() stays dumb and fee() is the computed one, on the quote in Contracts |
Price.FromAmount/ToAmount beside ADR-700’s QuantityBand |
ServicePrice, QuantityBand, BandedCharge (ADR-700, chargeable metrics) |
genuinely new beside it — ADR-700 bands a metered quantity of items with quantity > FromQuantity; this bands an amount of money [From, To) on a price row. Two banding mechanisms is a named drift risk; folding ADR-700’s onto the price row is a later refactor, surfaced in Notes |
PriceSelector { Key, AllowedValues } |
MetricDimension { Name, AllowedValues } (ADR-700) |
extend — the same shape, on the price type |
Price.Selectors, Price.FromAmount, Price.ToAmount, Price.Minimum, Price.Maximum |
RateBand(TermTypeId, FromAmount, ToAmount) (ADR-250) |
extend — ADR-250’s band generalised: the term is one selector among many; the band is inclusive-exclusive with an open top (Decision 1); a rate row gains its floor and cap |
PriceTypeEntry.Selectors, PriceTypeInfo.Selectors, PriceSelectorInfo |
PriceTypeEntry(Key, Label, Kind, IsActive) (ADR-419), PriceTypeInfo (ADR-416) |
extend — the type row declares the vocabulary its rows use, keys and values |
IPriceProvider.GetPrice(…, PriceContext) |
IPriceProvider.GetPrice(string, DateOnly) (ADR-419), IRateProvider |
extend — an overload; the two-argument form is the empty context |
WorkflowDispatchContext.PricingAttributes, PricingAttributes on the posting commands |
WorkflowDispatchContext.Properties (ADR-836 F16) |
extend — a second bag, because properties are recorded facts and pricing attributes are derived (region), and the lookup must not match against every property by accident |
price(type, valueDate, amount) |
price(type, valueDate), depositRate/noticeRate banded lookups (ADR-250 D4) |
extend — one more argument on the existing function; a banded rate lookup already exists for rate cards and is not touched |
CardType.Scheme |
CardDisputeReasonCode.Scheme (ADR-840, a string key) |
extend — the same vocabulary, on the card type where it belongs |
GetPriceMatrixQuery, PriceMatrixView |
GetPriceListReferenceQuery, IRepricingCardResolver (“card” already means a rate card in Pricing) |
extend — a per-type matrix read beside the list read; named matrix, not card |
card-currency-conversion-fee, card-atm-fee |
card-cash-advance-fee (ADR-838), card-replacement-fee (ADR-839) |
extend — price rows |
CardCurrencyConversionFeeCharged, CardAtmFeeCharged |
CashAdvanceFeeCharged (ADR-838), CardFeeCharged (ADR-839) |
extend — transaction types in the template |
ProcessCardPurchaseCommand, ProcessCardFeeCommand |
ADR-836 and ADR-839’s posting commands | extend — each gains the PricingAttributes bag; the refund and dispute commands do not |
ChangePriceCommand, RemovePriceCommand, AddPriceTypeCommand, EditPriceTypeCommand, AmendCardTypesCommand |
the existing settings commands | extend — carry the selectors, the band, the scheme |
the ListPrices endpoint |
the price-row read | extend — rows carry selectors, bands, floors and caps; the row id carries the series |
IPriceProviderResolver, IPriceTypeCatalog, PriceTypeId, PriceListId, PriceKind, CardChannel, CardEntryMode, CardClearingItem, TransactionPosted |
the seams as they are | reuse unchanged — read, resolved or carried through; IPriceTypeCatalog’s PriceTypeInfo gains the selector keys (above) |
Relies on
| Symbol | What it does today | What this ADR assumes |
|---|---|---|
PriceList.GetPrice |
The latest row of a type at or before the value date | Becomes the empty-context case of the selector lookup (D1) |
PricingPlan.ApplyAdjustments |
Overrides and percentages over a base price | Applies after the row is chosen (D3) |
IPriceProviderResolver |
The account’s price provider | The dispatcher binds it (ADR-839 F5) and now passes the context (D3) |
IPriceTypeCatalog |
Price types for a validator in another feature | Gains the selector keys so a settings page can show them (D2) |
CardClearingItem |
The clearing line with channel, entry mode, currencies, merchant country, DCC | The source of the card attributes (D4) |
RateBand.Matches |
ADR-250’s term-and-amount band match | The precedent for the inclusive band (D1) |
ADR-836’s purchase posting and DomesticCountry, ADR-838’s purchase workflow and
card-cash-advance-fee, ADR-839’s fee dispatcher and ADR-840’s dispute postings are relied on
as their plans declare them.
Worked example
Fixture: the simulated tenant; the demo customer’s credit card (card type credit, scheme
visa) and a second customer’s debit card (card type debit) on a current account; home
country ZA; the retail price list with the rows of Decision 5; a USD purchase at 18.50; dates
in a past month so a dated override is enterable.
| Date | Act | Priced | Posting |
|---|---|---|---|
| 2026-10-05 | a 100 USD e-commerce purchase on the credit card, billed 1 850.00 ZAR | card-currency-conversion-fee { currency-conversion: yes } → 0.0275 |
CardPurchase 1 850.00; CardCurrencyConversionFeeCharged 50.88 (1 850 × 0.0275 = 50.875, half-up to the cent) |
| 2026-10-05 | a 500 ZAR domestic contactless purchase on the same card | the fallback row → 0 | CardPurchase 500.00; no fee row |
| 2026-10-05 | a 100 USD purchase on the credit card dated 1 October, cleared today billed 1 850.00, with an override of 0.01 dated 3 October | the override does not apply before its date; the fee is priced at the line’s value date | the list rate: 50.88 |
| 2026-10-06 | a 3 000 ZAR ATM withdrawal in Johannesburg on the debit card | card-atm-fee { cross-border: no } → 0.02, floor 10 |
CardPurchase 3 000.00; CardAtmFeeCharged max(10, 60.00) = 60.00 |
| 2026-10-06 | a 500 ZAR ATM withdrawal, same card | the same row: 0.02 × 500 = 10 | CardPurchase 500.00; CardAtmFeeCharged 10.00 |
| 2026-10-07 | a 90 GBP ATM withdrawal in London, same card, billed 2 000.00 ZAR | card-atm-fee { cross-border: yes } → 0.03, floor 60; card-currency-conversion-fee { currency-conversion: yes } → 0.0275 |
CardPurchase 2 000.00; CardAtmFeeCharged max(60, 60.00) = 60.00; CardCurrencyConversionFeeCharged 55.00 |
| 2026-10-06 | a 200 ZAR ATM withdrawal, same card | 0.02 × 200 = 4, floor 10 | CardAtmFeeCharged 10.00 |
| 2026-10-08 | the credit card is reported stolen and replaced | card-replacement-fee { card-type: credit } → 0 |
nothing (ADR-839: a fee priced at nothing posts nothing) |
| 2026-10-08 | the debit card is replaced | the fallback row → 150 | CardFeeCharged 150.00 |
| 2026-10-09 | the credit card’s customer is given an override of 0.01 on card-currency-conversion-fee |
the override applies to the foreign row; the domestic row stays 0 | the next 100 USD purchase, billed 1 846.00, charges 18.46; a 500 domestic purchase still charges nothing |
| 2026-10-10 | a 1 846.00 ZAR foreign purchase on the debit card, no override | 1 846 × 0.0275 = 50.765 | CardCurrencyConversionFeeCharged 50.77 — half-up, where half-even would give 50.76 |
A tenant that adds channel to card-currency-conversion-fee’s selectors and a row
{ currency-conversion: yes, channel: atm } 0 makes the London withdrawal markup-free without a script
edit: the two-selector row is more specific than the one-selector row — after adding channel
with its values to the type’s selectors.
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 PricingPlan {
<<aggregate>>
PricingPlanId Id
AccountId AccountId
PriceListId PriceListId
ApplyAdjustments() «relies-on»
}
PricingPlan --> Account : AccountId
class PriceSettings {
<<settings>>
}
class FromAmount {
<<new>>
}
PricingPlan ..> FromAmount : declared
class ListPrices {
<<new>>
}
PricingPlan ..> ListPrices : declared
class Maximum {
<<new>>
}
PricingPlan ..> Maximum : declared
class Minimum {
<<new>>
}
PricingPlan ..> Minimum : declared
class PricingAttributes {
<<new>>
}
PricingPlan ..> PricingAttributes : declared
class Scheme {
<<new>>
}
PricingPlan ..> Scheme : declared
class Selectors {
<<new>>
}
PricingPlan ..> Selectors : declared
class ToAmount {
<<new>>
}
PricingPlan ..> ToAmount : declared
class WorkflowDispatchContext {
<<new>>
}
PricingPlan ..> WorkflowDispatchContext : declared
class CardClearingItem {
<<relies-on>>
}
class IPriceProviderResolver {
<<relies-on>>
}
class IPriceTypeCatalog {
<<relies-on>>
}
class PriceList {
<<relies-on>>
}
class RateBand {
<<relies-on>>
}
Consequences
Positive
- The demo claim: “price any card fee by scheme, region, channel, card type, currency or amount — in configuration, dated, with per-customer overrides.” Incumbents sell it as a custom build.
- One lookup for every priced thing. ADR-416’s rail fee by urgency, a notice fee by channel, a service fee by segment: the same selectors, no new mechanism.
- Nothing seeded changes meaning: a row with no selectors is today’s row.
- The auditor sees which attributes priced a fee, on the posting.
Negative / Trade-offs
- A selector vocabulary is the tenant’s own. The validator enforces kebab-case keys and the values each key declares; it cannot know that two tenants’ keys mean one thing. The matrix makes it visible.
- The hold does not include the fee. A foreign purchase that exactly exhausts the available overdraws by the markup at clearing. That is the industry’s behaviour, and ADR-837’s excess path carries it; a fee-inclusive hold is a later option.
- An
Amountrow and a floor or cap are in the price list’s currency, as every price row is today; an account in another currency reads another list.
Neutral
- The merchant settlement ADR reuses this shape with
merchant,merchant-categoryandschemeselectors; nothing here is card-only but the eight attributes Cards supplies.
Implementation Plan (Bites)
Three bites, one land; reseed: true. Bite 1 can start now; bite 2 after ADR-836, ADR-838,
ADR-839 and ADR-840 land; bite 3 after bite 1.
Bites, acceptance criteria, files touched, and status live in ADR-841-plan.md.
Changed during the grill
Grilled 2026-10-02 by the author against ADR-250, ADR-419, ADR-416 and the press; the operator’s standing instruction was to take the recommendations.
- Decision 1 and 3 — a rate row carries its floor and cap;
fee()computes. The draft composed a minimum in script from two types, and the press showed the composition defeating a per-customer override and contradicting its own wording (“10 up to 2 000 and 2% above” was neither reading). ARaterow now carriesMinimumandMaximum;price()stays dumb andfee()is the computed one; the ATM fee is one type. - Decision 1 — a band counts toward specificity, so a banded row beats an unbanded one of the same selectors; the tie check considers bands and ignores dates; an edit of an existing row is a replace, never a duplicate.
- Decision 5 — the fallback rows stay. Every flat row seeded today is the fallback; the credit-card rows and the foreign rows are added beside them, so a debit card prices as before. The credit card’s workflow does not carry the ATM row. A foreign ATM withdrawal in a foreign currency pays the markup too; the example’s London row says so.
- Decision 4 — eight attributes;
original-currencycarries the ISO code lower-case; the dispute postings carry the line’s bag; a fee charged at clearing stands on a refund. - Decision 3 — the bag’s keys are
$parameters camel-cased; a declared input wins. - Decision 7 — rewritten: “nothing moves” was false for the credit card’s replacement.
- Example — the override row moved to the markup, the London row gained the markup.
Contradiction press: 14 pairs, resolved as above — 1, 2 into Decisions 1 and 3 (fee()); 3,
4, 5, 6, 7, 8 into Decision 5 and 7; 9, 10, 14 into Decision 1 (specificity and the tie); 11,
12 into Decisions 2 and 4; 13 into Decision 4. The silent inputs — no matching row, an
override with no row, no amount against a band, case, null facet and currencies, refunds,
rounding, the fee’s currency, which amount, marginal rates, retiring a row, shrinking a type’s
keys, future-dated ties, $ names, DCC, an unset scheme, reseed scope, the ATM posting type —
are answered in Decisions 1 to 7.
Press block
- ATM band wording against the ATM formula.
- “This customer pays 5 for ATMs” against the formula.
- The foreign transaction fee on a London ATM withdrawal.
- The credit card’s ATM withdrawal: one fee or two.
- “0 otherwise”: a fallback row or a domestic row.
- Seeded rows with no selectors against seeded card rows.
- “Price exactly as before” against the new card-type rows.
- “Four card fees” against six types.
- The tie definition against the tie check: rows that never both match.
- The tie definition against the tie check: same selectors, different dates.
- Lowercase keys against ISO 4217 codes.
- One key, two vocabularies for
currency. - Seven attributes on every card posting, or two.
- Flat type or banded type.
Phase A (acceptance-test author, 23 questions), 2026-10-02. The rulings that changed a decision:
- Decision 1 — a type with selectors must carry its fallback row on every list that prices
it, so a lookup with attributes never misses where the plain one hits; a miss stays ADR-704’s
refusal (the draft’s “reads as 0” was false on
main). - Decision 1 — bands are inclusive-exclusive with an open top, a deliberate deviation from ADR-250, so adjacent bands never tie and “2% above 500” is expressible; zero-valued rows are allowed everywhere (a waived fee is a price of zero).
- Decision 3 — the floor lifts a charge, never creates one, and an override or adjustment
never turns a waived row into a charge; the guard reads the three-argument
price()so it sees the row the fee does; the quote carries the ISO 4217 minor unit for rounding. - Decision 3 — the
$parameters are a fixed union (declared selector keys plus the eight card keys), empty where absent, so every script compiles on a posting with no bag. - Decision 4 — a DCC line reads no currency conversion whatever its original currency; a blank merchant country reads domestic; (the plan grill then removed the dispute postings’ bag altogether).
- Decision 5 — the annual fee is out. ADR-838’s annual fee is scheduled on the account,
where no card attribute exists; a per-card annual fee is a later Cards-dispatched item. The
card type that prices differently is ADR-838’s
credit, not an inventedgold. - Decision 6 — the checks live on the settings aggregate, so the importer meets them too.
- Plan — the dispatcher’s
$exposure andpricing.properties move to bite 2, where a posting carries a bag;ListPricesQuerycarries the rows, not the reference query. - Filed for the coordinator, pre-existing: a pricing-plan override applies retroactively
(
PriceAdjustment.Appliesignores its start date) and its validator uses the wall clock; ADR-298’s regulatory advisory prices with an empty context and never sees a selected row.
Changed during the plan grill
Grilled 2026-10-02 on the plan’s signatures and mapping (ADR-692 D23); twenty-two press points, rulings taken on the operator’s standing instruction.
- Decision 4 —
cross-borderandcurrency-conversion, the schemes’ own words, replaceregionandcurrency;currency: foreignwas not a currency, andregionis a scheme term the acquiring ADR will need. The fee iscard-currency-conversion-fee. - Decision 2 — a selector declares its values (ADR-700’s
MetricDimensionshape), so a typo cannot silently charge the fallback. - Decision 3 — the fee formula lives on
PriceQuotein Contracts, the minor unit comes from the tenant’s currency setting (there is no ISO table in code), and the throwingQuotekeeps ADR-704’s refusal where it is; the scripting engine takes two decimal functions and no twin. - Decision 3 — the
$parameters are the eight card keys, declared on the card sources in the template validator; the tenant-key half of the union could not be validated at load. - Decision 1 — a series is retired by a marked row, since a row of 0 waives rather than retires; the fallback rule is a whole-list rule, so import order cannot break it.
- Decision 3 — an override on a waived row is refused, not silently ignored; the override applies from its own date (F-1796 fixed here, the seam this ADR rides).
- Decision 4 — only the purchase and the card fee carry the bag; a bag on a credit would
mislead the auditor, and filling it from ADR-840’s index would edit another ADR’s document.
channel: atmis one fact, from the processor or merchant category 6011; a malformed merchant country reads domestic. - Decision 6 —
GetPriceMatrixQuery, since “card” already means a rate card in Pricing and a payment card in this series; guarded as its sibling read. - Plan — bites 1 and 3 land first, demonstrable alone and the shape the acquiring ADR
builds on; bite 2 lands after the four card ADRs. The dispatcher edits move to bite 2; the
eleven
IPriceProvidertest doubles join bite 1’s files.
Pressed and held: typed ids where they exist; selector keys and values as strings with declared values as the guard; the markers; the wire shape of the bag; dated floors and caps; per-tenant settings; the override replacing the rate; eight attributes, four fee types; the half-open overlap rule; the tie check on the aggregate.
Changed during phase B
Three acceptance-test authors wrote 60 cold tests on 2026-10-02 (docs/adr/ADR-841-tests/).
Their findings, folded:
- Decision 3 — the waived-row refusal looks at every series, not the empty-context lookup; the plan’s wording would have refused the worked example’s own override.
- Decision 6 — the matrix read has its own key and Pricing’s route family, carries the list’s currency and minor unit, and its misses are named.
- Decision 1 — the fallback series cannot be retired while a selected row stands; a bag with no value for a key records no property for it; a malformed value is refused as malformed before it is checked as undeclared.
- Decision 3 — an
Amountrow’s fee on a zero amount is zero, as the rule says; the scenario said otherwise. - Decision 4 — one country parse, two null answers: pricing reads an unknown merchant country as home, ADR-836’s control check reads it as abroad; both on the customer’s safe side, said so they do not drift.
- Plan — files the authors found missing: the three override tests that break under the
waived-row refusal, the Scripting tests and runtime,
DatedLookupDefaultTests; the fixture’s helpers and its price list named; the fixture’s own types gain the fee rows. - Stale text struck: Decision 3’s command list,
$currency, the “inclusive edges” prior-art row, the vacuous 1 000 ZAR example row, the Notes’ dependency on ADR-840.
Notes
- Depends on ADR-836 (the purchase posting and
DomesticCountry), ADR-838 (the credit card’s purchase workflow and cash-advance fee), ADR-839 (the fee dispatcher binding the price provider) and ADR-840 (its postings carry no bag, by Decision 4). - Standards: ISO 4217 names a currency selector’s value; the register row exists. Scheme pricing rules (interchange) are the acquiring side’s.
- Refactoring opportunity, not this ADR’s: ADR-700’s quantity bands on chargeable metrics and this ADR’s amount bands on price rows are two banding mechanisms with opposite edge rules; folding the metric band onto the price row is a session’s work once both are stable.
- Merchant settlement, the rolling reserve and spend controls follow in the series.
Outcome
Landed in three bites over two lands, as designed. Most of bite 2’s dispatcher plumbing had already shipped with ADR-842’s merchant sale, so bite 2 added the card bag, the $ parameters and the retail rows. The selected card-fee rows sit on the retail Standard list only; the other lists carry the new types at 0, so no existing customer pays a new fee.