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-839: Cards and Authorisation: card renewal, replacement and card fees at day-end
Status: Shipped — 2026-10-03
Context
The Problem
A credential carries an expiry month (ADR-820). ADR-835 made expiry the credential’s state —
the oracle refuses an expired credential and the card stays Active so a renewal can replace
it — and named renewal as “a reissue with the same number and a new expiry, run by a day-end
step before the credential expires”, not yet designed. Nothing runs that step today: every card
the platform issues stops working at the end of its expiry month, and a clerk would have to
notice and reissue by hand.
Nor does any card act cost the customer anything. The proposal lists the card fees a bank charges — issuance, replacement, foreign transaction, ATM, monthly — “priced transactions off the price list”; ADR-835 left “fees of any kind” to the card products ADRs. A lost card is replaced for nothing.
What Already Exists
Card.Reissue(kind, credential, on)andReissueCardCommand(ADR-835 D3, D4): the processor answers first, the card records the credential, a plastic is ordered, the card is mirrored after commit.CardReissueKind.SameNumberNewExpirykeeps the token and every wallet token;NewNumbercloses the old credential and mints a new one.CardType.CredentialLifeYears, sent to the processor at creation.- The card day-end steps 41–45 (
SimulateCardClearing,FetchCardClearing,ImportCardClearing, ADR-836’sPostCardClearingandExpireCardHolds), each aIDayEndStepbehind thecards.issuingfeature, dispatching one tenant command. - ADR-836’s card postings: a system command in
Contracts/Accounts, run through the account type’scardPurchaseintegration, which names an operation that posts a transaction type. price('…', valueDate)in a workflow step, and a string workflow parameter.- The simulator (ADR-820 D8): mints a credential whose expiry is the processor clock plus the type’s life; reissues with the same number by moving the expiry on.
Scope
This ADR covers:
- A day-end step that renews every credential about to expire, through the processor.
- The replacement of a lost or stolen card as the existing reissue, with its fee.
- Card fees as configuration: issuance, replacement, renewal; posted to the card’s funding account through one new system posting.
- The demo: a simulated tenant whose cards expire soon enough to watch a renewal.
Out of scope: fees that vary by scheme, region, channel or amount (the price card ADR —
foreign-transaction and ATM fees wait for it), a monthly card fee (a row on the account type,
as the credit card’s annual fee is), bulk re-carding campaigns, emboss files and PIN mailers
(the processor’s), closing a card that was never renewed, and a renewal notice to the customer
(the correspondence feature can hook CardReissued today; a template is a later item).
Decisions
1. Renewal is a day-end step, and it is the existing reissue
RenewCardCredentialsStep runs at order 46, PreIncrement, non-critical, behind
cards.issuing, after ADR-836’s hold expiry. For every card in the tenant that is Active or
Suspended and whose primary credential’s expiry month ends within the card type’s
renewalLeadDays (a new card-type field, default 45, refused at load when it is not below the
credential’s life), it dispatches RenewCardCredentialCommand as the system. The card gains a verb of its own, Renew, a row in
ADR-835’s status table admitting Active and Suspended and excluded from the operator’s
menu — the clerk’s reissue keeps its row, which admits Active alone. “Within” is
inclusive and has no lower bound: a month that ends exactly at the lead renews, and a month that
has already ended renews too, until it succeeds. The set is read once per run, so a card is
dispatched once per day-end. The handler is ADR-835’s reissue with
SameNumberNewExpiry: the processor answers first, the card records the new expiry on the same
token, a plastic is ordered for a plastic credential, the card is mirrored. The event is
CardReissued with that kind; nothing new is minted. A device token on the card keeps the
expiry it was given: a wallet token’s life belongs to the token service, not to the card
number, so ADR-836’s oracle does not check expiry on a device credential at all — the processor
declines a dead token itself. Moving device expiries on a renewal would have changed what a
stored CardReissued means on replay (ADR-835 D7), and the grill refused it. The expiry is what the processor answers,
never a formula of ours; a processor that answers a shorter life than the type’s is recorded as
it answered, and the step will renew again when that shorter life nears its end.
A renewed credential’s expiry has moved on by a life that is longer than the lead, so the next
day’s step does not select it again. A LostOrStolen card is never renewed — its replacement
is a new number, and a card renewed in the morning and reported stolen in the afternoon simply
closes the credential it was just given. An Ordered card that was never activated is not
renewed either; it expires, and that is the one case the step leaves alone on purpose.
2. A renewal the processor refuses is tried again tomorrow
The step counts the renewals it made as its records, counts every failure — a processor refusal
or a transport fault alike, caught per card before any retry policy — in its note, naming the
card by its display name (or its last four alone when it has none), and completes whenever it
attempted anything; it is skipped only when nothing was due. A suspended card renewed stays
suspended, as a same-number reissue keeps the status. The card stays as it was. A plastic order
that fails after the processor has already renewed leaves the ledger a day behind the
processor; the next day’s renewal reissues once more and the two agree again. A
processor that is down for a week costs a week; a credential that reaches its expiry month
unrenewed is refused by the oracle (CredentialExpired, ADR-836) until the step succeeds, and
nothing closes the card. The lead days are the tenant’s cushion against exactly that.
3. Replacement is the existing reissue with a new number, and it carries a fee
A card reported lost or stolen (ADR-835) is replaced by ReissueCardCommand(NewNumber), as
today, and so is a new number for a damaged or compromised card. This ADR adds the fee: after
any new-number reissue commits, card-replacement-fee is cascaded to the card’s funding account
(Decision 4). Issuance charges card-issuance-fee the first time the card becomes Active —
on activation for a plastic card, on issue for a virtual one, and never again, so a replacement
plastic’s second activation is not a second issuance. Renewal, by the step or by a clerk’s
same-number reissue, charges card-renewal-fee — priced at nothing on the retail template,
present so a tenant that charges for renewal has a row to fill.
4. A card fee is one system posting, priced by the account’s workflow
ProcessCardFeeCommand(AccountId, TransactionId, PriceTypeId FeeType, TradingDate, ValueDate, SourceRef) joins ADR-836’s card postings in Contracts/Accounts. Accounts runs it as the
account type’s cardFee integration, which names an operation taking feeType as a string
input and posting CardFeeCharged for price($feeType, valueDate) — the current account to
Current, the credit card to Fees and Outstanding — with no guard, so a fee can take a
deposit below zero as a clearing line can (ADR-837 prices it). The posting carries the fee type
and the card’s id as dispatcher-supplied properties (ADR-836’s mechanism for the merchant), and
the card’s id as its source reference, so two fees on one statement read apart. The price
resolves as every price on the account does, through the account’s pricing plan; an account with
no plan prices nothing, so a bank that has not priced its cards charges nothing, and the
external-source path, which binds neither the price lookup nor the value date today, gains
both. A fee priced at nothing posts nothing; a price type with no price on the day is the
existing unpriced-on-date refusal, and the cascade dead-letters it. The account the fee lands on
is the first in the card’s funding rule, the account the card draws on; a credit card’s single
entry is its revolving account. The fee’s transaction id is derived from facts — the card for
an issuance, the new token for a replacement, the token and the new expiry for a renewal — so a
redelivered cascade posts once.
The fee is published after the card’s own commit, as the mirror is (ADR-835 D4), and never
blocks the card act: a fee on a funding account that is not active is forgone — a retry could
never collect it — and the card records CardFeeForgone with the reason, so the auditor finds it
on the card’s own stream and not in a log; one the type cannot take (no integration) dead-letters
as a configuration fault; the card is renewed, replaced or activated regardless. A card whose
funding rule names no account yet records the same event. A fee is the bank’s charge for
something it has already done. The fee carries the trading date of the card event that caused
it, as both its trading and value date, so a renewal handled after midnight still posts on its
day. The properties carry the price type’s and the card’s id parts; a renewal’s id names the
token and the answered expiry month, so a processor that answers the same month twice is
charged once.
5. Fees are price types, not fields
card-issuance-fee (0 on the retail template — a debit card is free to issue), card-replacement-fee
(150), card-renewal-fee (0) are rows in PriceSettings, read by name. A tenant that charges
for issuance fills the row; no code and no card-type field names a fee. A row priced at nothing
posts nothing; a row that is missing, or has no price on the day, is the pricing feature’s own
unpriced-on-date refusal (ADR-704), and the cascade dead-letters it — the key is a parameter, so
no load-time check can see it; the template carries all three rows. Fees that vary by scheme
or channel are the price card’s; this ADR’s three are flat.
6. The simulated tenant’s cards expire soon enough to watch
The simulator mints a credential with the processor clock plus the card type’s life in years.
The processor facet (CardProcessorSettings, ADR-820) gains simulatedCredentialLifeMonths,
read only by the simulator — at mint and at reissue, the answer being the tenant’s trading date
plus the months, because the simulated processor’s “today” is the tenant’s business day and the
probe walks it; the simulator keeps each card’s life so a reissue answers the life it was minted
with, and every simulated expiry now comes from the trading date, the years path too — and
replacing the years when set. The simulation seed step sets it to two on
the simulated tenant (the facet is seeded by that step, not by YAML, and only on a tenant the
seed builds), so a card issued today expires in two months and the day-end forty-five days
before that month’s end renews it; the probe advances the trading date to that day. A life
inside the lead would renew daily, so the facet refuses months that do not clear the largest
lead on the tenant’s card types (the default lead when the tenant has none), and the card
types refuse a lead the facet’s months do not clear; the simulation seed runs the same check and
orders itself before the sample cards. The field is validated on any facet and ignored by a live
processor.
Contracts
Ids — none new.
Commands — RenewCardCredentialCommand(CardId) (LedgerTM.Cards, ISystemCommand, the
day-end step’s dispatch); ChargeCardFeeCommand (LedgerTM.Cards, ISystemCommand, the
published cascade); ProcessCardFeeCommand (LedgerTM.Contracts/Accounts, ISystemCommand,
beside ProcessCardPurchaseCommand), its fee type a PriceTypeId.
Events — CardFeeForgone(CardId, PriceTypeId FeeType, string Reason, DateOnly On) on the
card’s stream (LedgerTM.Cards). CardReissued carries the kind; a renewal is
SameNumberNewExpiry.
Queries — none new.
Consumed from LedgerTM.Contracts — ProcessCardPurchaseCommand (the shape),
TransactionSource.
Consumed from LedgerTM.Cards — ICardProcessor.ReissueAsync, ICardProcessor.OrderPlasticAsync, CardReissueKind, CardCredential, CardExpiry. Each lived in Contracts when this ADR shipped, and moved to its only reader on 2026-10-21 (ADR-755 ruling).
Consumed from LedgerTM.Infrastructure.Contracts — IDayEndStep.
Changed — Card gains the Renew verb and WasEverActive; CardType gains
RenewalLeadDays; CardProcessorSettings gains SimulatedCredentialLifeMonths;
ExternalIntegrations gains CardFee; TransactionSource gains CardFee; ADR-836’s decider
skips the expiry check on a device credential (a landing note on its plan).
Removed — none.
Shares a file, unchanged — ProcessDebitOrderPaymentCommand, ProcessStandingOrderPaymentCommand,
ProcessBankDepositCommand, ProcessCashDepositCommand, ProcessCashWithdrawalCommand and
ProcessCardRefundCommand sit in the file ProcessCardFeeCommand joins; their shapes do not move.
Prior art
| Declared | Search returned | Verdict |
|---|---|---|
RenewCardCredentialCommand |
ReissueCardCommand (ADR-835), MirrorCardToProcessorCommand (system, after commit) |
genuinely new — the system-dispatched twin of the user’s reissue; the user command is ICommand and four-eyes eligible, the step’s is not |
RenewCardCredentialsStep |
ExpireCardHoldsStep (ADR-836, 45), PostCardClearingStep (44) |
extend — one more card step, order 46 |
ProcessCardFeeCommand |
ProcessCardPurchaseCommand, ProcessCardRefundCommand (ADR-836), ProcessBankDepositCommand |
extend — the same shape, a fee type in place of a merchant |
CardFeeCharged (transaction type) |
CardPurchase, CardRefund (ADR-836), ServiceFeeCharged |
extend — a transaction type row |
card-issuance-fee, card-replacement-fee, card-renewal-fee |
card-annual-fee, card-late-payment-fee, card-cash-advance-fee (ADR-838), unarranged-overdraft-fee (ADR-837) |
extend — price type rows |
CardType.RenewalLeadDays |
CardType.CredentialLifeYears |
extend — the other half of the credential’s life |
CardProcessorSettings.SimulatedCredentialLifeMonths |
CardProcessorSettings.DomesticCountry (ADR-837) |
extend — a facet field the simulator alone reads |
ExternalIntegrations.CardFee, TransactionSource.CardFee |
CardPurchase, CardRefund (ADR-836) |
extend |
CardReissued, CardReissueKind |
ADR-835, ADR-820 | reuse unchanged — the Renew verb emits the same event with the same meaning |
ChargeCardFeeCommand |
MirrorCardToProcessorCommand (the published after-commit system command) |
extend — the same shape, publishing a fee instead of a mirror |
CardFeeForgone |
CardCredentialRemoved, CardDetailsRevealed (card events recording an act’s outcome) |
genuinely new — an auditor’s record of a charge the bank chose not to make |
PriceTypeId |
ADR-422’s typed price-type id | reuse unchanged — the fee type on both commands |
IDayEndStep |
ADR-068 | reuse unchanged |
CardExpiry, CardCredential |
ADR-820’s credential and its expiry month, with its JSON converter | reuse unchanged — the step reads the month |
ProcessDebitOrderPaymentCommand, ProcessStandingOrderPaymentCommand, ProcessBankDepositCommand, ProcessCashDepositCommand, ProcessCashWithdrawalCommand, ProcessCardRefundCommand |
the external-source commands in the file ProcessCardFeeCommand joins |
reuse unchanged — siblings in one file; none of their shapes moves |
Relies on
| Symbol | What it does today | What this ADR assumes |
|---|---|---|
ReissueCardCommand |
The user’s reissue: processor first, record, order plastic, mirror | The renewal does the same as the system (D1) |
ICardProcessor |
ReissueAsync with a kind; OrderPlasticAsync |
Unchanged |
CardReissueKind |
SameNumberNewExpiry, NewNumber |
Renewal is the first, replacement the second |
CardCredential |
Token, BIN, last four, expiry, kind | The expiry month is what the step reads |
CardType |
Credential kinds, funding shape, life in years, device rule | Gains the renewal lead days (D1) |
IDayEndStep |
A step with an order, a phase, a criticality and a feature key | The renewal step at 46 (D1) |
ProcessBankDepositCommand |
A system posting from outside Accounts, run through the type’s integration | The card fee follows it (D4) |
CardProcessorSettings |
The processor facet: connection, domestic country (ADR-837) | Gains the simulated life (D6) |
ADR-836’s ProcessCardPurchaseCommand and its cardPurchase integration are relied on as its
plan declares them; the fee posting is their third sibling.
Worked example
Fixture: the simulated tenant, the demo customer’s virtual debit card issued 2026-10-05 on
a type with a three-year life, renewalLeadDays 45; the facet’s simulated life two months, so
the credential expires 2026-12 (ends 2026-12-31). card-replacement-fee 150, the others nothing.
| Date | Day-end step 46 sees | Does |
|---|---|---|
| 2026-10-05 | 87 days away | nothing |
| 2026-11-16 | 45 days away, exactly the lead | renews: the processor answers the same token with the expiry it computes (the simulator: the trading date plus two months, 2027-01; a live processor, its life on); a wallet token on the card keeps its own; CardReissued(SameNumberNewExpiry); a virtual card orders no plastic; card-renewal-fee prices at 0, so nothing posts |
| 2026-11-17 | expiry 2027-01, 75 days away | nothing |
| 2026-11-20 | the customer reports the card stolen; a clerk reissues with a new number | the old credential closes, a new one is minted, and ProcessCardFeeCommand('card-replacement-fee') posts 150 to the call deposit as CardFeeCharged, source the card, properties the fee type and the card |
Had the processor refused on the 16th, the step’s note names the card and the 17th tries again; had it refused for seven weeks, the oracle would decline the card from 1 January until the step succeeds.
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 PriceSettings {
<<settings>>
}
class OrderPlasticAsync {
<<new>>
}
class Renew {
<<new>>
}
class RenewalLeadDays {
<<new>>
}
class SameNumberNewExpiry {
<<new>>
}
class SimulatedCredentialLifeMonths {
<<new>>
}
class WasEverActive {
<<new>>
}
class CardCredential {
<<relies-on>>
}
class CardProcessorSettings {
<<relies-on>>
}
class CardReissueKind {
<<relies-on>>
}
class CardType {
<<relies-on>>
}
class ICardProcessor {
<<relies-on>>
}
class IDayEndStep {
<<relies-on>>
}
class ProcessBankDepositCommand {
<<relies-on>>
}
class ReissueCardCommand {
<<relies-on>>
}
Consequences
Positive
- No card dies in a drawer. Renewal is unattended and visible in the day-end log.
- Replacement, issuance and renewal are priced by three rows, posted through one command.
- The demo shows a renewal within six weeks of issue, from configuration, and the probe walks the trading date to it.
Negative / Trade-offs
- One processor call per renewal, in the day-end; a tenant with many cards renewing on one day pays a longer step. Non-critical, so a slow processor delays nothing else.
- A fee the account refuses is retried by the cascade and may dead-letter; the card act stands. The auditor sees the dead letter, not a reversed renewal.
- A fee is flat. A tenant that prices replacement by scheme waits for the price card.
Neutral
- The user’s reissue is unchanged; the step reuses its handler path.
- The simulated-life field is inert on a live processor.
Outcome
Landed as planned in three bites: card fees through the cardFee integration with CardFeeForgone, renewal at day end (RenewCardCredentialsStep), and a simulated credential life with its seed, probe and guide. The full suite first ran at the land gate; the lane had run only filtered integration.
Implementation Plan (Bites)
Three bites, one land; reseed: true. Bite 1 starts after ADR-836 lands; bites 2 and 3 can start now.
Bites, acceptance criteria, files touched, and status live in ADR-839-plan.md.
Changed during the grill
Grilled 2026-10-02 by the author against ADR-835, ADR-836, the simulator and the press; the operator’s standing instruction was to take the recommendations.
- Decision 1 — the window’s edges. “Within the lead” is now inclusive at the lead and open at the past, so an already-expired credential keeps being tried; the lead is refused at load when it is not below the life, so a renewed card is never selected the next day; the set is read once per run.
- Decision 1 — whose expiry. The processor’s answer, never a formula of ours; the worked example was rewritten to say so.
- Decision 3 and 4 — the fee is cascaded, in both decisions’ words; a closed account’s dead letter and a card with no funding account are named.
- Decision 5 — a missing price row was first ruled a load-time diagnostic; phase A found the key is a parameter, and the plan grill made it ADR-704’s unpriced refusal.
- Decision 6 — the simulated life replaces the years, which the draft said both ways.
- Decision 2 — indefinite retry pressed on cost and held: a day-end step that logs and completes costs nothing when it fails; closing the card instead would cost the customer.
Plan grill (12 press points, 2026-10-02): the renewal is a verb and a status-table row of its own, not a second guard; fee ids derive from facts, not a version the handler cannot see; the fee is published, not returned, and carries its date; the fee type is a typed price-type id; the external-source path binds the price lookup and the value date, and an account with no pricing plan charges nothing; a fee on an inactive account is forgone, not retried; the unpriced refusal is ADR-704’s; device tokens keep their own expiry and ADR-836’s oracle does not check it; the simulator’s clock for a credential’s life is the tenant’s trading date; the facet refuses a simulated life inside the lead; the step command carries no tenant.
Phase B (three authors, 2026-10-02): a forgone fee is a card event, not a log line; the
step’s records are its renewals and its note its refusals; a renewed suspended card stays
suspended; the fee’s dates are the card event’s trading date; the renewal id names the answered
month; every simulated expiry comes from the trading date and the simulator keeps each card’s
life; both the facet and the card types check the lead against the simulated life, and the seed
does too; a template test keeps every card-funding type’s cardFee rows and the three price
rows together; the stale lines earlier folds left behind were corrected.
Phase A (the cold author’s questions, 2026-10-02): the external-source path binds no price lookup today and gains it; a virtual card is issued active, so the issuance fee is charged the first time a card becomes active and never again; every new-number reissue is a replacement; the clerk’s same-number reissue charges the renewal fee too; the renewal admits a suspended card (a verb and a table row, after the plan grill); a renewal was to move device tokens’ expiry, which the plan grill reversed; a transport fault counts as a refusal; the step completes whenever it attempted anything; a missing price row was given its own code, which the plan grill replaced with ADR-704’s; the fee’s id was to derive from the card event’s version, which the plan grill replaced with facts; the posting names the fee type and the card; the simulated life is two months, set by the simulation seed step, read at mint and at reissue; the demo’s “day two” became “within six weeks”.
Contradiction press: 11 pairs, resolved as the simulated life’s wording (Decision 6, changed), the lead against the life (Decision 1, validator), whose expiry (Decision 1, changed), the already-expired credential (Decision 1, changed), the fee’s wording (Decisions 3 and 4, aligned), the closed account (Decision 4, closed), no funding account (Decision 4, closed), a missing price row (Decision 5, closed), a double renewal in one run (Decision 1, closed), renew then stolen (Decision 1, closed), and the exact boundary (Decision 1, inclusive).
- The simulator mints “clock plus the type’s life” and “expires next month” for one input. Real.
- A lead at or above the life re-selects the renewed card every day. Real.
- The processor’s answer or a formula sets the new expiry. Gap.
- “Within the lead” against a credential already past its month. Gap.
- D3 posts in the handler, D4 cascades. Gap.
- A closed funding account against “inactive”. Silent.
- A card with no funding account has no first entry. Silent.
- A missing price row against a zero one. Ambiguous.
- Whether the eligible set is re-read within a run. Silent.
- Renewed in the morning, stolen in the afternoon. Silent.
- A credential expiring exactly at the lead. Boundary. Pairs: 11
Notes
- Depends on ADR-835 (Shipped) and ADR-836 (Accepted): the reissue, the card postings and
the
cardPurchaseintegration the fee follows. Bite 1 starts after ADR-836 lands; bite 2 can start now. - ADR-837 and ADR-838’s types (
CurrentAccount,CreditCard) gain thecardFeeintegration in their own lanes if they land first, or here if this lands first; a landing note on each. - Disputes, the price card and merchant settlement follow in the series.