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

Scope

This ADR covers:

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

Negative / Trade-offs

Neutral


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.

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).

  1. The simulator mints “clock plus the type’s life” and “expires next month” for one input. Real.
  2. A lead at or above the life re-selects the renewed card every day. Real.
  3. The processor’s answer or a formula sets the new expiry. Gap.
  4. “Within the lead” against a credential already past its month. Gap.
  5. D3 posts in the handler, D4 cascades. Gap.
  6. A closed funding account against “inactive”. Silent.
  7. A card with no funding account has no first entry. Silent.
  8. A missing price row against a zero one. Ambiguous.
  9. Whether the eligible set is re-read within a run. Silent.
  10. Renewed in the morning, stolen in the afternoon. Silent.
  11. A credential expiring exactly at the lead. Boundary. Pairs: 11

Notes