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-838: Cards and Authorisation: the revolving credit card

Status: Shipped — 2026-10-03


Context

The Problem

A credit card spends the bank’s money against a revolving limit. The card series so far funds a debit card from a deposit (ADR-835, ADR-836) and from a current account with an overdraft (ADR-837). The revolving product exists only as a dormant CreditCard row in the ca-retail package, a tenant nobody runs, and that row gets the one rule every implementation gets wrong: it decides the interest-free period once, at the start of a cycle, from the amount due. Real products decide it at the payment due date, and when the statement was not paid in full they charge interest on each purchase from its own transaction date.

The industry list of what a revolving product must do is short (proposal §3.2):

What Already Exists

Scope

This ADR covers:

Out of scope: card renewal and replacement at day-end (the next ADR), disputes and chargebacks, the attribute-banded price card and foreign-transaction fees (the pricing ADR), rewards, instalment plans and balance transfers, a cash-advance sub-limit at authorisation, a redesigned statement document (the scheduled statement is issued as today; its figures are the account’s), and a per-card sub-limit on a shared account (corporate cards).


Decisions

1. CreditCard is a retail-package account type, asset nature

The retail package gains CreditCard, shaped on the dormant row and corrected. The ca-retail row stays as it is (no package shares rows; ADR-837 D1).

Position Category Meaning
PurchaseBalance standard what the customer owes for purchases
CashAdvanceBalance standard what they owe for cash advances
Fees standard fees charged and unpaid
Arrears standard minimum payments missed (Decision 7)
PurchaseAccrued, CashAdvanceAccrued accrual interest accrued, capitalised at the close
UnallocatedPayment standard a payment before allocation; zero after it, unless the customer paid more than they owed, when the credit waits here for the next purchase
Outstanding memorandum the sum of what is owed — purchases, cash advances, fees; the position the facility is wired to. A waiting credit is not a lower debt until it is applied, and arrears is an overlay (Decision 7), so neither moves it
StatementBalance, AmountDue, MinimumPaymentDue memorandum the last close’s figures; AmountDue and MinimumPaymentDue fall as payments arrive
CyclePurchases, StatementPurchases memorandum the purchases of the current period, and of the period the last statement covered (Decision 6)
DeferredCycleInterest, DeferredStatementInterest memorandum the interest those purchases would have earned, accrued daily and charged or forgiven at the due date (Decision 6)
GracePeriodStatus memorandum 1 while purchases are interest-free, 0 while revolving; set to 1 by the opening transactions

Outstanding exists because a limit integration wires one position (ADR-050 §2): every transaction type that moves a standard balance moves Outstanding by the same amount, so the facility sees one figure. It sits in a balance group of its own, so a list that sums the group never counts it beside the balances it sums. A load-time check refuses a type whose facility is wired to a memorandum roll-up when any transaction type moves a standard balance without the matching roll-up leg, or when the roll-up shares a summed balance group — the invariant is configuration, and a missed leg would understate the limit silently. One holder role, regulatoryRegime (Decision 8), the call deposit’s servicingUnit and taxReportingRegime, and a paymentGraceDays property (default 25). The inbound integrations a deposit carries (bankDeposit, debitOrder) post Payment, so a customer pays by transfer or by debit order as they pay a loan; the card integrations post the purchase and the refund (Decision 4).

2. The revolving limit is a facility wired Raise to Outstanding

A Facility of type CreditCard (a new facility-type value) on the customer, wired to Outstanding with ADR-837’s direction: Raise — the loan reading: usage rises as the balance rises. ADR-837’s three symbols are bound for a Raise wire too: FacilityLimit (the amount less the customer’s other accounts’ usage), FacilityAvailable (less reservations), and Excess = max(0, wired position − FacilityLimit). ADR-837 binds them for BelowZero; this ADR binds them for every wire, so a loan reads its own headroom in an expression as well.

3. The card’s available is the facility’s headroom less the holds

The card’s funding rule has one entry, its own revolving account (ADR-835 D5). The oracle’s AccountAvailability (ADR-836 D4, ADR-837 D4) reads, for an asset-nature type, no ledger contribution — the standard positions are what the customer owes, not money they can spend — so Available = max(0, FacilityAvailable − wired position + credit balances − ExternalReductions): ADR-837’s FacilityAvailable adds the account’s own usage back, so the account’s own Outstanding comes off again; a standard position that reads below zero on an asset type is money the customer overpaid and may spend, so it comes back; then the holds already against the account; never below zero. With 20 000 granted, 12 000 owed and a 500 hold: 7 500; with nothing owed and 2 500 waiting as a credit: 22 500. A liability type keeps ADR-837’s reading. The nature decides; nothing names a product. Two cards on one revolving account share that one figure and the one facility; nothing is per card.

4. The cash advance is the same clearing post through a different door

ADR-836’s clearing post runs the type’s cardPurchase workflow. On CreditCard that workflow branches on the merchant category the posting carries: a cash category (6010, 6011) posts CashAdvance and the cash-advance fee; anything else posts Purchase. The merchant category reaches the workflow as a parameter ($merchantCategory), as amount does; a refund reverses through cardRefund the same way. No new command, no new door.

5. The statement cycle is the type’s statement schedule

A monthly Statement schedule, declared as the type’s statementSchedule so the Statements feature issues the scheduled statement as it does for a deposit (ADR-080). At the close, end of day, in sequence:

Row Does
capitalise PurchaseAccrued and CashAdvanceAccrued into their balances
StatementClose sets StatementBalance = Outstanding
AmountDueSet sets AmountDue = StatementBalance
MinimumPaymentSet sets MinimumPaymentDue = min(StatementBalance, max(StatementBalance × minimumPaymentPercent, minimumPaymentFloor) + Arrears) — a minimum still raised on arrears at the close is asked for again with the next
OverLimitFeeCharged if Excess > 0, price('card-over-limit-fee', valueDate)

A purchase, a refund or a payment dated the close day posts during the day and is in the statement; the close rows run at the end of it, the over-limit fee first so the statement carries it. The first close falls one month after opening (addMonths(StartDate, 1)), never on the opening day, and monthly on that day of the month thereafter, clamped to a shorter month’s end. The annual fee first falls a year after opening, never on the opening day. A close posts its statement rows even when nothing is owed, so a card that was used and settled inside the cycle still gets its statement.

The due date is a PaymentDue schedule, monthly, anchored paymentGraceDays after the first close; a grace of twenty-eight days or more is refused at load, because the due date would then fall after the next close and read the wrong statement. A payment reduces AmountDue and MinimumPaymentDue by itself, floored at zero, as triggered rows; a payment on the due day itself counts, because the due-date rows run at the end of that day. A payment larger than what is owed leaves the remainder in UnallocatedPayment as a credit, and the next purchase drains it before it owes anything. A refund reduces the balance it refunds and nothing else: the amount due is what the statement said, and the catch-up prices the days the money was actually outstanding.

6. The interest-free period is decided at the due date, with one catch-up posting

GracePeriodStatus starts at 1. Purchases accrue daily only while it is 0; cash advances accrue daily always. At the due date, end of day:

The catch-up is interest accrued day by day and held in memorandum positions until the due date decides it. CyclePurchases takes every purchase as it posts and is reset at the close; at the close, just before the reset, StatementPurchases is set to it. While the account is interest-free, two daily rows accrue what those purchases would earn — CyclePurchases into DeferredCycleInterest, StatementPurchases into DeferredStatementInterest — at the purchase rate on the day, so a rate change is priced on the day it happens. At the close the statement’s deferred interest is set from the cycle’s, and the cycle’s is reset with its purchases. At the due date, not paid in full: the catch-up is DeferredStatementInterest + DeferredCycleInterest, posted to PurchaseAccrued, and both are reset; paid in full: DeferredStatementInterest is reset to nothing and DeferredCycleInterest keeps running toward its own due date. A balance carried from an earlier statement and paid in full inside its own grace is never in either.

Nothing new enters the vocabulary: the rows are Set, daily accrual and capitalisation, which every deposit and loan already uses, and a re-walk after a back-dated line reprices them day by day exactly as it reprices any accrual (ADR-837 D7). The grill rejected a history-replaying function for this: the day-walk and the re-walk would have disagreed. The daily accrual row on PurchaseBalance runs only while revolving, and the catch-up did not touch PurchaseBalance, so the day after the due date accrues on what is still owed. Each deferred row rounds to four decimals as every full-precision accrual does, so the worked example’s catch-up is the sum of forty-six such rows: 302.46, a cent under the single-computation figure.

7. Allocation, fees and arrears are configuration

8. The credit card is a credit facility under the NCA

CreditCard declares regulatoryRegime (National Credit Act §8(3), as ADR-837’s overdraft does), categorises every transaction type, and the za-nca retail cell gains a Reg 42 ceiling row for CreditCard in the shape of the others (unsourced, marked so, ADR-298 D3a). NCA §101 names the charges a credit agreement may carry — interest, an initiation fee, a service fee, credit insurance, default administration charges and collection costs — and no over-limit fee is among them, so the package carries none; the gb retail cell adds it. The late payment fee is a default administration charge (DefaultAdmin), the annual and cash-advance fees Fee (ADR-329 D19 then suppresses them under a monthly-charging hold, as it suppresses every fee — a held card pays no annual fee, which is intended).

The regime’s interest ceiling must bind on a named rate: today RegulatoryLimitEnforcement checks only a structure-bound rate property, and ADR-837’s overdraft rates and this card’s are named rate types, so the row would be decorative. Enforcement extends to the rate('…') references an Interest-category scheduled row reads, each checked on its own against the ceiling as a bound property is, at agreement date (ADR-298 D7); a rate that cannot be priced on that date — unknown, or with no fixing — refuses the activation rather than letting it through; and the guard context it evaluates in gains the rate lookup — without which every activation of a type whose scheduled rows read a named rate throws. A row that sums two named rates passes each on its own; the register row says so. ADR-837’s lane meets the same wall first; it is recorded on both plans. The standards register’s §8(3) row (ADR-837) gains the credit card, and a §101 row records which fees the platform’s retail card carries under the NCA.

9. The card and the demo

The retail card types gain credit: FundingShape.SingleAccount, fundable type CreditCard, plastic and device credentials, ATM allowed. The account viewer’s header shows the cycle’s figures — statement balance, amount due, minimum — because their position rows carry headline: true, a per-row flag on the type’s position binding that the header honours whatever the category; and the facility figure ADR-837 added for an overdraft serves the revolving limit too, labelled by nature, reading the oracle’s own available so the screen and the decline agree. The demo customer gets a ZAR CreditCard account, a CreditCard facility of 20 000 and a credit card; the probe buys, closes a statement, pays the minimum, reaches the due date and shows the catch-up. reseed: true.


Contracts

Ids — none new. CreditCard is an AccountTypeId key and a facility-type value.

Commands — none new. The clearing post is ADR-836’s ProcessCardPurchaseCommand.

Events — none new.

Queries — none new.

Consumed from LedgerTM.Contracts — ProcessCardPurchaseCommand, ProcessCardRefundCommand, IAccountAvailabilityReader (ADR-836), IFacilityAvailabilityReader, LimitIntegrations (internal to Limits since ADR-1224) (ADR-837), StatementCycleReachedTrigger.

Changed — AccountAvailability’s reading for an asset-nature type (D3); the facility symbols bound for a Raise wire, with Excess computed from the wired position at every site ADR-837 computes it from Current (D2); the card workflow’s parameters gain merchantCategory (D4); RegulatoryLimitEnforcement checks named rates and evaluates with the rate lookup (D8); PositionType gains headline; ADR-837’s account-detail figure for a wired facility serves a Raise wire too, under a nature-neutral name its lane picks. IAccountStatementCloseReader is added: the clearing post reads the account’s last statement close, so a late presentment posts value-dated the clearing date (F-1794).

Removed — none.


Prior art

Declared Search returned Verdict
CreditCard (account type) the dormant ca-retail row genuinely new row, corrected shape — the package model has no shared base (ADR-837 D1); the ca-retail row stays
CreditCard (facility type) Overdraft (ADR-837), PersonalLoan, MortgageBond extend — one more lookup value
CyclePurchases, StatementPurchases, DeferredCycleInterest, DeferredStatementInterest (memorandum positions) StatementBalance, AmountDue on the dormant row; InterestSuspense on the loan types extend — memorandum rows the daily accrual fills and the close and due date set and reset; the suspended-interest pattern, pointed the other way
Outstanding (memorandum position) Balance on loans, Arrears extend — a roll-up position so one wire sees one figure
PurchaseInterestCatchUp, MinimumPaymentOverdue, OverLimitFeeCharged the dormant row’s PurchaseInterestAccrued, LateFee, AnnualFee extend — transaction type rows
card-annual-fee, card-late-payment-fee, card-over-limit-fee, card-cash-advance-fee unarranged-overdraft-fee, unpaid-fee, service-fee extend — price type rows
CreditCardPurchase, CreditCardCashAdvance (rate types) Call, Overdraft, UnarrangedOverdraft extend — rate-type rows
AccountAvailability, IAccountAvailabilityReader ADR-836 (Accepted) extend — the asset-nature reading
FacilitySymbols, IFacilityAvailabilityReader, LimitIntegrations ADR-837 (Accepted) extend — bound for Raise wires too
ProcessCardPurchaseCommand, ProcessCardRefundCommand ADR-836 (Accepted) reuse unchanged — the workflow reads the merchant category the command already carries
StatementCycleReachedTrigger ADR-080 reuse unchanged
AccountTypeId the strongly typed id every account type key carries reuse unchanged
IAccountStatementCloseReader IAccountStatementDataProvider, AccountStatementData, CloseAccountStep genuinely new — the data provider takes the period as input; the clearing post needs the last close date itself (F-1794)

Relies on

Symbol What it does today What this ADR assumes
WhenConditionStep, PostTransactionStep Workflow steps that post with the balances the previous step left Allocation, the due-figure reductions and the refund branch (D7)
TransactionOperation Debit, Credit, Set on a position rule Set writes the statement figures (D5)
StatementScheduleSettings (was AccountType.StatementSchedule, moved by ADR-1025) Names the schedule whose row marks a statement cycle The monthly close issues the scheduled statement (D5)
SchedulesFiredTrigger (was StatementCycleReachedTrigger, replaced by ADR-1025) Fired when the cadence row posts; Statements issues the period (ADR-080) Unchanged
AccountValuation Runs scheduled rows by timing and sequence; triggered rows only inside the walk The close and the due-date rows run in order (D5, D6); allocation is a workflow, not a triggered row (D7)
GrantFacilityCommand Grants a facility to a counterparty Grants the revolving limit (D9)
RegulatoryLimitsSettings A dated ceiling row per account type and category (ADR-298) Gains the CreditCard row (D8)

ADR-836’s AccountAvailability and ADR-837’s FacilitySymbolResolver and IFacilityAvailabilityReader are relied on as their plans declare them; this ADR changes the first’s reading for an asset-nature type and binds the second for every wire.

The activation-time ceiling check (RegulatoryLimitEnforcement, internal to Accounts) checks a structure-bound rate property against the regime’s ceiling at agreement date today; this ADR extends it to named rates (D8).


Worked example

Fixture: za-retail, the demo customer, a ZAR CreditCard with a 20 000 facility, purchase rate 20%, cash-advance rate 24%, minimum 5% floored at 200, 25 grace days, late fee 150. Statement closes 30 September; due 25 October.

Date Event PurchaseBalance AmountDue MinimumPaymentDue GracePeriodStatus
1 Sep the previous statement’s 5 000, paid in full on 20 September inside its own grace; not in any catch-up 5 000.00 5 000.00 250.00 1
10 Sep purchase 12 000 17 000.00 5 000.00 250.00 1
20 Sep payment 5 000 12 000.00 0 0 1
30 Sep close: statement 12 000, due 12 000, minimum max(600, 200) + arrears 0 = 600 12 000.00 12 000.00 600.00 1
20 Oct payment 600, allocated to purchases 11 400.00 11 400.00 0 1
25 Oct due date: not paid in full, was interest-free → catch-up = deferred interest: 46 daily rows of 12 000 × 20% / 365 = 6.5753 (21 days 10–30 Sep in DeferredCycleInterest, moved to DeferredStatementInterest at the close; 25 days 1–25 Oct) = 302.46 to PurchaseAccrued; both deferred positions reset; status → 0 11 400.00 11 400.00 0 0
26 Oct onward daily purchase accrual 11 400 × 20% / 365 = 6.25 a day 0
30 Oct close: statement 11 400 + accrued, minimum 5% 0

Had the customer paid 12 000 on 20 October: no catch-up, status stays 1, October’s purchases accrue nothing. Had they paid nothing: at 25 October the catch-up posts, MinimumPaymentDue 600 moves to Arrears, the late fee posts, and collections sees one day past due on 26 October.

The card’s available on 10 September before the purchase: 20 000 − 0 holds. After the purchase posts: 8 000. With a 500 hold outstanding: 7 500.


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 Facility {
    <<aggregate>>
    Decimal Amount
    Decimal Available
    FacilityId Id
    Decimal UsageByAccount
    Decimal Utilisation
    Double UtilisationPercent
    Decimal UtilisationRatio
    CounterpartyId CounterpartyId
    CurrencyId CurrencyId
    LookupValueId FacilityTypeId
  }
  Facility --> Counterparty : CounterpartyId
  class Statement {
    <<aggregate>>
    StatementId Id
    String StatementNumber
    StatementStatus Status
    AccountId AccountId
    CounterpartyId CounterpartyId
    OperatingEntityId OperatingEntityId
  }
  Statement --> Account : AccountId
  Statement --> Counterparty : CounterpartyId
  Statement --> OperatingEntity : OperatingEntityId
  class RegulatoryLimitsSettings {
    <<settings, relies-on>>
  }
  class CreditCard {
    <<new>>
  }
  Statement ..> CreditCard : declared
  class Current {
    <<new>>
  }
  Statement ..> Current : declared
  class Excess {
    <<new>>
  }
  Statement ..> Excess : declared
  class Raise {
    <<new>>
  }
  Statement ..> Raise : declared
  class RegulatoryLimitEnforcement {
    <<new>>
  }
  Statement ..> RegulatoryLimitEnforcement : declared
  class AccountType {
    <<relies-on>>
  }
  class AccountValuation {
    <<relies-on>>
  }
  class GrantFacilityCommand {
    <<relies-on>>
  }
  class StatementCycleReachedTrigger {
    <<relies-on>>
  }
  class TransactionOperation {
    <<relies-on>>
  }
  class WhenConditionStep {
    <<relies-on>>
  }

Consequences

Positive

Negative / Trade-offs

Neutral


Outcome

Landed as planned in five bites: the credit card on the retail template, its statement cycle, payment allocation, interest-free rule, revolving tap, cash advance and headline figures. The late-presentment ruling (F-1794) needed a new IAccountStatementCloseReader the plan never declared; the land declared it.

Implementation Plan (Bites)

Five bites, one land; reseed: true. Every bite starts after ADR-836 and ADR-837 land. Bites, acceptance criteria, files touched, and status live in ADR-838-plan.md.


Changed during the grill

Grilled 2026-10-02 by the author against the proposal, the dormant row, the code and the press; the operator’s standing instruction was to take the recommendations.

Contradiction press: 10 pairs, resolved as overpayment (Decision 1 and 5, closed), the due-date order (Decision 7, closed), the catch-up basis (Decision 6, equivalence stated), the window ends (Decision 6, changed), the due-day payment (Decision 5, closed), the available floor (Decision 3, closed), a refund after the close (Decision 5, closed), a posting on the close day (Decision 5, closed), two cards on one account (Decision 3, closed), and the minimum after the arrears move (Decision 7, closed).

  1. An overpayment past everything owed: the allocation chain runs dry and UnallocatedPayment cannot be zero. Real.
  2. The due date with an unpaid minimum: if the arrears move runs first the late fee’s condition is never true. Real, ordering unresolved.
  3. The catch-up’s prose says per purchase, the formula says from the period start. Wording gap; they coincide because the balance before the first purchase is zero.
  4. The window’s ends are unnamed; the example’s 40 + 5 split implies one convention. Silent.
  5. A payment on the due day: before or after the evaluation. Silent.
  6. A hold larger than the headroom drives available negative. Silent.
  7. A refund after the close: whether the amount due moves. Gap.
  8. A posting dated the close day: where it falls in the close sequence. Silent.
  9. Two cards on one account. Silent.
  10. Whether the minimum is zeroed when it moves to arrears. Silent. Pairs: 10

Phase A (the cold author’s questions, 2026-10-02): Decision 6 changed twice more — the window on PurchaseBalance charged a previous statement paid in full inside it, so the catch-up now prices CyclePurchases and StatementPurchases, two memorandum positions the close sets and resets, on the statement’s purchases alone and in full (a part payment does not reduce it), and posts to PurchaseAccrued; the example is 302.47. Decision 3 nets the account’s own draw (ADR-837’s symbol adds it back). Decision 7 makes arrears an overlay that never consumes a payment. Decision 8 drops the over-limit fee from the package under NCA §101 and classifies the late fee as a default administration charge. Decision 5 anchors the first close a month after opening, the due schedule on it, refuses a grace of twenty-eight days or more, and posts the over-limit fee before the close. Decision 1 opens the grace status at 1 through the opening transactions.

Plan grill (14 press points, 2026-10-02): Decision 6 changed a third time and for good — positionDays and the schedule-occurrence dates are gone; the catch-up is deferred interest accrued daily into two memorandum positions and charged or forgiven at the due date, which a re-walk reprices consistently and which prices a rate change on its day. Decision 7 moves allocation from triggered rows (which run only inside the day-walk) to the payment workflow’s steps, and the arrears raise becomes one two-legged transaction. Decision 8 extends the regime ceiling to named rates and binds the rate lookup in the activation check, which ADR-837 meets first. Fee categories are Fee; Outstanding sits in its own balance group; every bite waits for ADR-836 and ADR-837. The due date leaves the header for the schedules panel: a next occurrence on the detail would need a scheduler inside a query handler.

Phase B (five authors): the catch-up is 302.46, the sum of forty-six rounded rows; the catch-up includes the current period’s purchases, said plainly; a waiting credit is spendable; the cash branch drains fees first; the annual fee first falls a year after opening; a missed minimum is added to the next; the close posts even at zero; the arrears raise moves no balance and the late fee does; a named rate that cannot be priced refuses activation; a roll-up wire is validated at load; headline sits on the type’s position binding; the detail’s facility figure is the oracle’s available under the name facilityHeadroom, which this ADR gives ADR-837’s overdraft once both have landed.


Notes

Amendment — net balance (2026-11-11)

A payment posts to UnallocatedPayment and the allocation rows move Outstanding, so an enquiry on Outstanding showed one payment as a fee line and a purchase line, and an overpayment showed no negative balance. A memorandum position NetBalance now reads Outstanding less UnallocatedPayment: every type that moves Outstanding moves it, Payment and RefundCredit credit it, and the three allocation types leave it alone. A payment is one line, an overpayment reads negative, and Outstanding stays the limit position (D1 stands). NetBalance sits in its own balance group, net, and the layout adds a Balance view. Applies to the card-issuer and retail-bank templates. Tenants provisioned before this need a settings migration step. Test: CreditCardCycleTests.