01The claim
Every core we would sit beside runs its cards in a separate system. The card account lives in a card management system, the customer's other accounts live in the core, and the two meet in a nightly file. A card that is an ordinary product of the customer's ledger, funded by whichever of their accounts a rule chooses, is a claim none of them can make from that shape.
The market has settled into three roles, and the split is what makes this buildable by a two-person shop. The scheme member holds the BIN and carries scheme liability. The issuer processor runs the real-time authorisation switch, the scheme connections, the PAN vault, tokenisation and card production. The card management system and ledger owns the cardholder, the account, limits, statements, pricing and disputes. Modern cores build only the third role: Temenos partners with Paymentology, Thought Machine and Mambu with Marqeta and Thredd. Only the old monoliths (TCS BaNCS, Oracle FLEXCUBE, Way4, SmartVista) carry a native card module, and those are the stand-alone card systems every banker remembers.
Four product lines were put on the table: retail debit and credit cards, corporate expense and virtual cards, merchant acquiring and billing, and wallets and non-card instruments. Working through them produces eight subsystems, because all four stand on one processor seam, the three issuing products share one card aggregate and one authorisation oracle, and acquiring needs a transaction-priced settlement engine that nothing in the issuing half provides.
| Subsystem | What it is | Rests on | |
|---|---|---|---|
| Card Connectivity | The processor seam | The anti-corruption layer. One contract for authorisation requests, card commands, token provisioning and the clearing feed; Paymentology first, with a simulator. | — the spine |
| Cards | The card aggregate | Physical, virtual and wallet credentials on one card, its lifecycle, its controls, and the funding rule that names which account pays. | Card Connectivity |
| Authorisation | The oracle | Answers the processor per transaction from the counterparty's available balance and limits across accounts, and places the hold. | Cards + the Claim register |
| Card Products | Retail current account, overdraft, revolving credit | Account-type configuration: a retail current account, an overdraft facility, and the revolving credit card with its statement cycle. | Account types, Facilities |
| Disputes | Chargebacks, both sides | A dispute aggregate per transaction with scheme stages and deadlines; provisional credit and its clawback; the acquiring mirror. | Cards, Merchant Settlement |
| Transaction Pricing | The attribute-banded price card | A price chosen by scheme, region, card type, channel, currency and amount band, dated, with per-merchant overrides. | Pricing |
| Merchant Settlement | Acquiring and billing | Feed ingest, priced transactions, the merchant account, the rolling reserve, T+n payout by rail in the merchant's currency. | Transaction Pricing, Rails, FX |
| Spend Controls | Corporate expense cards | Per-card ceilings, category and merchant restrictions, just-in-time funding from a pooled account, the corporate administrator. | Cards, Authorisation, Client Channel |
Retail debit leads, on the oracle, against Paymentology. It is the smallest issuing product, it forces the three foundations every other product stands on (the processor seam, the card aggregate, the oracle), and it is the one a prospect can watch in two minutes: tap a card, see the hold appear on the customer's current account, see it become a posting the next morning. Credit follows as configuration, because the revolving product already exists as a dormant account type. Acquiring is the last lane. It is where the lived experience sits and its two net-new pieces are generic concepts the platform should want anyway, but it shares nothing with issuing beyond the price card and the feed, and it has no bank customer to ride in on: it waits for a PSP or an acquirer to name the room. Corporate expense cards close the issuing set before that, once the client channel exists.
The ledger side is bounded and this document sizes it. The critical path is not. A processor contract, a BIN sponsor or scheme membership, and the processor's scheme certification all sit outside our code and each runs months. The buyer already has a card system, so the first sale is a bank launching a new programme, a lender adding a card to a loan, or a corporate bank offering expense cards to its clients. It is not a bank replacing a card ledger that works.
02What we already own
The platform is further into this than it looks, for the same reason it was further into corporate banking: lending and deposits needed the same plumbing. What is missing is the card itself, real-time authorisation, and everything an acquirer prices.
| Capability | State | Where it already lives |
|---|---|---|
| Current account | Partial | CorporateCurrentAccount in the corporate package: deposit, withdrawal, interest, fees. The retail package has none. Nothing in the aggregate refuses a negative balance: a withdrawal is refused by an availabilityGuard expression on the operation, per account type, so an overdraft is a guard change plus a facility attachment |
| Revolving credit card product | Dormant | CreditCard and RevolvingCredit in the unused ca-retail template: purchase and cash-advance balances, a monthly statement schedule, statement close, amount due, minimum payment, a grace-period flag that suspends purchase accrual, and payment allocation fees → cash advance → purchase. Never run against a live tenant |
| Dated hold on available balance | Built | The Claim register (ADR-251): amount, position, direction, origin, backing, release by date or by event. This is the shape of the authorisation hold, but a claim is an event on the account's own stream and is released only at day-end, so the hold itself lives on the card (section 7). Missing: the card-side hold, a per-account projection of card holds, real-time release, an expiry default per merchant category |
| Limit against unsettled exposure | Built | Facility with Reserve / Assume / ReleaseReservation (ADR-794). An overdraft is a facility whose account may go negative; the reservation is the same shape as a hold |
| Cleared versus booked money, T+n | Built | ADR-083 and ADR-115: accounts carry only settled facts; instructions carry a trading date and a value date; the rail settlement profile gives lead days per direction. This is the merchant payout delay and the card clearing lag, already correct |
| Rails, beneficiaries, nostros, suspense | Built | SEPA, SWIFT, ACH, Bacs, BankservAfrica, PayShap (ADR-306, ADR-414, ADR-783); ExternalAccount and the beneficiary profile (ADR-413, ADR-713); operating-entity bank accounts as nostros; a full Suspense project; PostingGroup routing per transaction type |
| Feed ingest with AI field mapping | Built | Mt940Parser, Camt053Parser, CSV, BAI2; FormatProfile proposes a mapping from a sample file for a human to approve (ADR-094). Missing: the card attribute model on a feed line (MCC, terminal, auth code, scheme, channel, DCC flag) and a per-line pricing hook |
| Back-dated reversal with FX cascade | Built | ADR-261. A chargeback that reverses a settled purchase weeks later, in another currency, is this cascade with a new origin |
| Per-transaction pricing | Partial | PriceList gives a price by type and date; PricingPlan adjusts it by percentage or override, globally or per type (ADR-419, ADR-422); rail fees and charge bearer (ADR-416). No banding by scheme, region, card type, channel, currency or amount |
| Retention and rolling reserve | New | Collateral is a loan security with a one-shot release (ADR-027, ADR-423): the wrong shape. Nothing withholds a percentage of a settlement batch and releases it on a date |
| Counterparty, roles, relationships | Built | Typed, dated roles on an account (ADR-327), party relationships (ADR-057). A cardholder is a role; a merchant is a counterparty with a merchant category. Neither role nor category exists yet |
| Statement cycle | Built | Statements ride day-end per account (ADR-080); the schedule and scheduled-transaction mechanism is what the dormant credit card uses for its cycle |
| Day-end orchestration | Built | IDayEndStep registry with phases, criticality and restart (ADR-068, ADR-289, ADR-772). A settlement batch and a reserve release are steps, not a scheduler |
| Client channel, corporate users | Partial | ADR-695 and ADR-801: a channel user under one agreement with a closed operation list. The corporate card administrator is that user with two more operations |
| Card identity, credentials, lifecycle | New | Nothing. The word card in the code means a rate card or an approval card |
| Real-time authorisation, velocity rules | New | Nothing evaluates a transaction as it happens. Compliance clearance is per counterparty; four-eyes is per back-office change |
| Chargeback lifecycle | New | DisputeCollectionAuthority is a debit-order dispute with one stage. A card dispute has five, each with a scheme clock |
Most card ledgers get value dating wrong, because they were built around the authorisation and treat clearing as a correction. LedgerTM was built the other way round: an account carries only settled facts, and a hold is a claim against available balance until the clearing line lands (ADR-115, ADR-251). “The card balance the customer sees is the one the auditor sees” is a claim the stand-alone card systems cannot make, and the reason a chargeback here is a back-dated reversal rather than a manual journal.
03The products
What a bank is actually buying, in the vocabulary its cards and merchant teams use. Scheme terminology follows Visa and Mastercard, because an RFP in this category reads like a scheme rulebook.
3.1 Retail debit card
A debit card spends the customer's own money. Every authorisation is answered from the available balance of a funding account, and the purchase posts when the scheme clears it, one to three days later. The product is nine parts configuration and one part real-time plumbing:
| Element | What it is | In LedgerTM |
|---|---|---|
| Current account | The transactional account the card draws on. Interest-bearing or not, fee-bearing, statemented. | The corporate current account promoted to the retail package |
| Overdraft | An agreed limit below zero, priced, reviewed. | A Facility attached to the CurrentAccount type, and the type's availability guard reading Current + FacilityAvailable > 0 instead of Current > 0. Both are configuration; the attachment already exists on loan types |
| Authorisation hold | Money set aside when the merchant asks, released when the clearing line arrives or the hold expires. | A Claim with a new origin and a default expiry per merchant category |
| Card controls | Daily and per-transaction ceilings, channel switches (online, abroad, ATM, contactless), block and unblock. | Properties on the card aggregate, evaluated by the oracle |
| Card fees | Issuance, replacement, foreign transaction, ATM, monthly. | Priced transactions off the price list |
3.2 Retail credit card
A credit card spends the bank's money against a revolving limit. The industry list of what a revolving product must do is short and every item is already sketched in the dormant template:
- Two balances at two rates. Purchases and cash advances accrue separately; cash advances accrue from day one, purchases only once the interest-free period is lost.
- The statement cycle. Monthly close, statement balance, amount due, minimum payment as the greater of a percentage and a floor, a payment due date some days after close.
- The interest-free period. Pay the statement balance in full by the due date and purchases in the next cycle accrue nothing. Pay less and interest applies from the transaction date. This is the rule every implementation gets subtly wrong, and the one to press in the grill.
- Payment allocation. Fees first, then the most expensive balance, then the rest. Regulated in the UK and EU (highest rate first); a tenant rule elsewhere.
- Fees. Annual, late payment, over-limit, cash advance, foreign transaction.
- The limit. A revolving facility; utilisation is the settled balance plus the outstanding holds.
Statement closes 30 September with purchases of 12,000 and no cash advances. Statement balance 12,000; amount due 12,000; minimum payment max(12,000 × 5%, 200) = 600. The grace flag reads AmountDue <= 0 at the next cycle start. If the customer pays 12,000 by 25 October, the flag stays set and October's purchases accrue nothing. If they pay 600, the flag clears, the remaining 11,400 accrues at the purchase rate from 1 October, and the 600 allocates fees → cash advance → purchase, which here is all purchase.
What the template gets wrong, and the grill must press: the interest-free rule is evaluated once, at cycle start, from the amount due. Real products evaluate it at the payment due date and back-date accrual to the transaction date when the balance was not paid in full. The rule this document commits to: at the payment due date, if the statement balance was not paid in full, one catch-up interest transaction posts for the cycle, computed across each purchase from its own transaction date; from then on purchases accrue daily from their transaction date until a statement is again paid in full, at which point the interest-free period returns. That needs one expression function the vocabulary does not have yet, a day-weighted sum over the cycle's purchases, and no change to the accrual engine.
3.3 Corporate expense and virtual cards
A corporate holds one funding account and issues many cards to staff, each with its own ceiling and rules. Three shapes are sold:
| Shape | How it is funded | Who sells it today |
|---|---|---|
| Pre-loaded | A sub-balance per card, topped up by the administrator. Simple, and money sits idle. | Soldo, prepaid programmes |
| Just-in-time | Every authorisation draws on the pooled account at the moment of spend, subject to the card's ceiling. Nothing is pre-loaded. | Pleo, Payhawk, Moss on Marqeta or Enfuce |
| Virtual per purpose | A card per supplier, campaign or trip, single- or multi-use, with an expiry and a ceiling. Generated on demand, never printed. | Moss, Spendesk, Amex vPayment |
A corporate card sits under the corporate counterparty, and the employee is a named cardholder on it, not its owner; a funding rule may only name accounts the card's owning counterparty holds or services (ADR-327). The oracle makes the second and third shapes native: the funding rule on a corporate card names the pooled account, the ceiling is a control on the card, and a virtual card is a credential without plastic. The expense-management half (receipts, approvals, accounting export) is the SaaS vendors' product and stays out of scope; what a bank can sell is the card and the controls, offered to its corporate clients inside the client channel (ADR-695, ADR-801), where the corporate administrator issues, caps and cancels cards for their own staff.
3.4 Merchant acquiring and billing
An acquirer receives the merchant's card sales from a processor, prices each transaction, pays the merchant the net amount after a delay, and holds back a reserve against future chargebacks. The product is the pricing engine plus a settlement account with unusual parameters:
| Parameter | What it is | Typical values |
|---|---|---|
| Pricing model | Interchange++ (interchange + scheme fee + acquirer margin, each passed through) or blended (one rate). Per merchant, per card type, per region, per channel. | IC++ for larger merchants; blended 1.4 to 2.9% for small |
| Settlement delay | T+n business days from the transaction date to the payout. | T+1 to T+3; T+7 or more for high-risk |
| Rolling reserve | A percentage of each day's settlement withheld and released after a fixed period. | 5 to 10% for 90 to 180 days |
| Fixed reserve | A collateral amount built up from settlements to a target and held for the life of the agreement. | One to two months of chargeback exposure |
| Settlement currency | The merchant's chosen payout currency per transaction currency, converted at a posted rate plus a margin. | Like-for-like, or everything to one currency |
| DCC | Dynamic currency conversion at the terminal: the cardholder pays in their own currency and the margin is shared with the merchant. | A revenue-share line in the feed |
| Chargeback handling | A chargeback debits the merchant, or the reserve, and carries a fee; the merchant has a window to represent. | 15 to 25 fee per case; dispute ratio thresholds near 1% |
Every one of those is a parameter on a merchant agreement, and every one is a claim against configuration depth. The acquiring feed is the only new external interface; everything after it is the ledger doing what it already does, with a price card in front.
3.5 Wallets and non-card instruments
Two different things share the word wallet, and only one is ours to build.
- A device wallet (Apple Pay, Google Pay, Samsung Pay) is a card in a different skin. The scheme's token service issues a device token for an existing card; authorisations arrive naming the token; the issuer sees a second credential on the same card. Nothing new in the ledger beyond the credential.
- A stored-value wallet (a prepaid balance, a closed-loop wallet, a mobile-money account) is a current account with a credential and no bank account number. Configuration, not code.
- Alternative payment methods on the acquiring side (Alipay, WeChat Pay, PayPal, account-to-account such as PayShap or Pix) arrive in the feed as a scheme with a channel. They are priced off the same price card because scheme is vocabulary.
- Payment gateways and website plug-ins are the merchant's integration to the acquirer and belong to Adyen, [redacted], Stripe and their peers. We never build one; we receive what they settle.
04How a card transaction actually moves
Where the certainty comes from at each step, and which of our contracts carries it. Authorisation is a promise; clearing is a fact; settlement is money.
4.1 Authorisation, the hold and the clearing line
Thandi holds a current account with 4,200 and an overdraft facility of 2,000. A hotel authorises 5,000 at check-in. The oracle computes available as 4,200 + 2,000 − 0 (holds) = 6,200, approves, and appends a hold of 5,000 to the card, keyed to the current account and expiring in 30 days, the hotel default. Her available balance reads 1,200; her ledger balance still reads 4,200, and no interest is charged on an overdraft she has not yet used. At check-out the hotel clears 2,650. The clearing line matches the auth code: a purchase of 2,650 posts with the check-out value date, the claim releases in full, and her available balance returns to 3,550. Had the hotel cancelled at 14:00, the processor's reversal message would have released the hold at 14:00, not at day-end. Had nothing arrived at all, a day-end step over cards would have expired it on day 30. Next day, with the hold still open, she tries groceries for 1,500: current has 1,200 available, so the oracle walks to savings, finds 15,000 under a notice claim and 0 available, and declines with insufficient funds. No hold is ever split across two accounts.
4.2 What the oracle actually decides, and in what order
The processor sends one message per authorisation: card token, amount, currency, merchant category, merchant country, channel, an entry mode, and whether the cardholder was present. The oracle answers approve, decline with a reason, or partial approval, inside the processor's timeout, which is a few seconds at most. The order of checks is fixed and each is a declared reason code:
- Card status. Active, not expired, not blocked, not reported lost.
- Card controls. Channel switches, per-transaction ceiling, daily and monthly velocity, merchant category and country rules. For a corporate card, the administrator's ceiling.
- Funding rule. An ordered list of the customer's accounts, all in the card's billing currency. The oracle walks it and places the entire hold on the first account whose available covers the amount; nothing is ever split. An overdraft is not a list entry, it is the facility on the current account, so current, then savings already means current, its overdraft, then savings. A credit card's list has one entry, its own revolving account, whose available is the facility's; one walk serves both products.
- Available balance. Settled balance less existing claims plus the unused facility, on the chosen account. For a credit card, the revolving facility's available.
- Place the hold. A claim on the account, with the scheme's default expiry for that merchant category (seven days for most, thirty for hotels and car hire).
Currency is decided before the message reaches us. The processor converts a foreign transaction to the card's billing currency at the scheme rate plus the issuer's margin, so the hold and the posting are always in the funding account's currency; the original amount and currency travel with the clearing line for the statement, and the foreign-transaction fee is a priced transaction.
Fraud scoring is deliberately not in that list. The processor and the scheme run it before the message reaches us, and a bank that wants its own model plugs it into the processor, where the data is. The oracle applies the customer's and the bank's rules, not a risk model.
When the clearing line exceeds what was held
A restaurant adds a tip, an offline terminal clears with no authorisation, a hold expired on day thirty and the merchant clears on day thirty-two. The scheme has already settled the money with the processor, so the bank has paid. The clearing line posts unconditionally, to the account the hold was keyed to, or to the first account in the funding rule when there is no hold. It is a settled fact from a source that outranks the availability guard, the same standing the instruction settlement step already has (ADR-251), and the guard on customer-initiated withdrawals is untouched. If the account cannot bear it, the balance goes negative past whatever facility it has: an unarranged overdraft, which is the abnormal state AccountNature already names, carrying a configured fee and rate, and visible to collections like any arrears. The alternative, parking the shortfall in a suspense account, hides a payment the bank has made and puts the purchase somewhere the customer's statement does not show. A stand-in approval, made by the processor from a pushed balance while we were unreachable, arrives the same way: a clearing line with no hold, posted under the same rule.
4.3 The funding rule, and the cross-account claim
4.4 The card's own life
A card is ordered, produced, shipped, activated, active, suspended, reported lost or stolen, replaced, expired and renewed, closed. Every transition is a command to the processor and an event back from it, and each carries a fee or not by configuration.
| Transition | Who initiates | What crosses the seam | What we record |
|---|---|---|---|
| Order | Bank staff, the customer in the channel, or the corporate administrator | Create card: product, embossed name, delivery. Paymentology allocates the PAN and returns a token reference, the BIN and the last four | The card, with its credential and its funding rule |
| Produce and ship | Processor and bureau | The processor sends the bureau file; the bureau prints, packs and posts | Status events as they arrive; nothing to do |
| Activate | Customer, by app, ATM or first PIN transaction | An activation event | Active; the first authorisation may now be approved |
| Suspend, block | Customer, bank, or the oracle after repeated declines | Set status | Every later authorisation declines with the reason |
| Lost or stolen | Customer | Block, then reissue with a new PAN | Old credential closed, new credential on the same card, replacement fee |
| Renew | Day-end, some weeks before expiry | Reissue with the same PAN and a new expiry | New expiry on the credential; the customer keeps every wallet token |
| Wallet provisioning | Customer, from the device | The scheme asks the processor, the processor asks us: may this card go on this device, and does the customer need a one-time code first | A device token as a second credential; block one without the other |
| Close | Bank or customer | Close the card; the account survives | Closed; open holds release on their dates |
4.5 Disputes, on both sides of the table
A card dispute is a state machine with scheme clocks, and the same machine runs in mirror image for the acquirer. The stages are the schemes' own:
| Stage | Issuer side | Acquirer side | Clock |
|---|---|---|---|
| Retrieval | Ask for the transaction record before disputing | Supply it from the merchant | Days |
| First chargeback | File through the processor into Visa Resolve Online or Mastercom, with a reason code. Provisional credit posts to the cardholder if the tenant's rule says so | The chargeback lands in the feed; debit the merchant, or the reserve, plus the fee | 120 days from the transaction for most codes; up to 540 for some |
| Representment | Receive the merchant's evidence; accept, or press on | The merchant has a window to send evidence | Around 30 days (Mastercard 45; Visa 18 outside the US since 2025) |
| Pre-arbitration | Escalate with a fee at stake | Respond or accept | Days |
| Arbitration | The scheme rules; the loser pays the case fee | Weeks | |
What the ledger does at each stage is nothing new. Provisional credit is a posting whose timing is a tenant rule per reason-code class: fraud and unauthorised-use codes credit on day one, as PSD2 requires; merchandise and service codes credit on outcome. A lost dispute reverses the credit; a won one against a purchase that already carried catch-up interest reverses that interest's share through the same cascade, while the interest-free flag is never re-decided retroactively. When the merchant is also the tenant's own acquiring customer, the two sides still run as two aggregates linked by the scheme case reference, each fed by the processor; the scheme remains the arbiter and no on-us short cut exists in the first version. A loss reverses it through the back-dated reversal cascade (ADR-261), in the original currency at the original rate. On the acquiring side a chargeback that exceeds the merchant's free balance consumes the oldest reserve claim. Case fees are priced transactions. What is new is the dispute aggregate itself: one per disputed transaction, with the stage, the reason code, the deadline, the evidence references and the outcome. That is the auditor's trail, and it is the one the stand-alone card systems keep in a case-management tool outside the ledger.
4.6 Acquiring, worked through
Reserve as a lump. A reserve held as one balance cannot be released per day and cannot be consumed oldest-first, so the merchant's statement stops reconciling after the first chargeback. Modelled as one claim per settlement day, each with its own release date, both come for free. Pricing at payout instead of at receipt. If the price is chosen when the batch settles, a merchant re-priced mid-period gets two rates on one statement with no record of which line got which. Price the transaction when the feed line lands, and store the price-card row it hit. Cross-currency at the wrong point. Convert the net after fees, once, at the payout; never convert the gross and then the fee separately, or the merchant's statement and the GL disagree by the rounding of every line.
4.7 Our contracts, and a simulator for the processor
Card Connectivity is a boundary, not a utility. Above it, nothing knows Paymentology's field names; below it, nothing knows what a claim is. Four contracts cross the line, and every one is exercised by a simulator in the component tests before a sandbox key exists:
| Contract | Direction | Carries | Tempo |
|---|---|---|---|
| Authorisation request | Processor → oracle | Token, amount, currency, MCC, merchant country, channel, entry mode, auth id; back: approve, decline reason, partial amount | Real time, seconds |
| Card command | Cards → processor | Create, set status, reissue, set controls, order plastic; back: token reference, BIN, last four, expiry, status events | Request and reply |
| Token provisioning | Processor → Cards | Device, wallet, card token; back: approve, step-up, decline | Real time |
| Clearing and settlement feed | Processor → ingest | One line per cleared item: auth id, final amount, currency, fees, MCC, DCC, reversal and chargeback flags; plus the scheme settlement totals | Daily file |
The feed goes through the same FormatProfile path as a bank statement, because that is what it is: a statement of what the processor did on our behalf, reconciled against the holds we placed. The reconciliation is the control that catches a hold with no clearing line, a clearing line with no hold, and a total that does not match the scheme's settlement advice.
05Regulatory reality
Cards are the most rule-bound product a bank sells, and almost every rule is either the processor's to keep or a tenant setting. The list below is what a prospect will ask, and where each answer lives.
| Rule | What it requires | Whose problem | In LedgerTM |
|---|---|---|---|
| PCI DSS v4 | Any system that stores, processes or transmits a full PAN is in scope for the full standard, audited annually. | Ours to avoid | We hold a token reference, the BIN and the last four. A truncated PAN is not cardholder data. A build-time test scans every event contract and read model for a sixteen-digit field. The customer's PCI attestation names Paymentology, not us |
| Scheme membership | Only a licensed institution with principal or associate membership may issue under a scheme BIN. Everyone else issues under a sponsor's BIN. | The bank's | The BIN is a row on the card product. A sponsored programme and a principal programme differ in configuration, not code |
| Scheme certification | Every switch and clearing connection is certified by the scheme, per release. | The processor's | None. This is the whole reason the switch is never ours |
| EU Interchange Fee Regulation | Consumer interchange capped at 0.2% debit and 0.3% credit; commercial cards exempt; acquirers must offer unblended pricing on request. | Both | Caps are dated price-card rows; the merchant statement shows the three components. ADR-298 already models a regulatory regime as a price limit |
| PSD2 strong customer authentication | Two factors on online payments above the exemption thresholds, via 3-D Secure. | The processor's, with the issuer's exemption policy | Exemption rules are card controls the oracle reports; the challenge itself is the processor's |
| Unauthorised transaction refund | PSD2: refund by the end of the next business day unless fraud is suspected. UK and SA codes of practice say similar things less precisely. | The bank's | Provisional credit is a tenant rule on the dispute aggregate: post on day one, or post on outcome |
| Payment allocation order | UK CCA and EU CCD: repayments allocate to the highest-rate balance first. | The bank's | The triggered-transaction order on the account type; the dormant template's order needs checking against this |
| South Africa, 2026 | PASA's recognition as the management body is withdrawn in August and September 2026; a directive letting a non-bank issue in its own name is a May 2026 draft; interchange is set by SARB determination. | The bank's | Nothing changes in the ledger. A non-bank tenant issues under a sponsor bank until the directive lands, then in its own name: a BIN row either way |
| Dispute monitoring programmes | Visa and Mastercard fine acquirers whose merchants exceed dispute ratios near 1% and a case count near 100 per month. | The acquirer's | A per-merchant ratio on the read model, and a reserve percentage that can be stepped up by rule when it is breached |
| AML, KYC, sanctions | Cardholder and merchant due diligence; transaction monitoring. | The bank's, in its compliance tooling | Compliance clearance per counterparty gates issuance (existing verdict machine); monitoring stays outside, as it does for every other product |
| Standards register | New rows for docs/standards/README.md: PCI DSS v4 (scope avoidance, not compliance), ISO 18245 merchant category codes, ISO 7812 issuer identification, ISO 8583 (via the processor, named so a prospect sees we know it), EU IFR 2015/751, PSD2 SCA RTS | ||
“If Paymentology goes down, do my cards stop?” Yes, and they would with any processor. The honest addition is that with the oracle model a processor outage stops authorisations but loses no money and no record, because every approved hold and every cleared line lives in our stream; and stand-in processing, where the processor answers from a rules file when the issuer host is unreachable, is a standard processor feature that a bank should insist on. Our side of stand-in is a nightly push of card status and a conservative available balance, which is the batch option of section 1 kept as a fallback rather than as the design.
06Competitive landscape
Five vendor populations, and LedgerTM would sit in the one that is nearly empty: a ledger that treats a card as a product of the customer's accounts rather than of a separate system.
| Population | Vendors | What they are, and what we are up against |
|---|---|---|
| Issuer processors | Paymentology, Marqeta, Thredd, i2c, Enfuce, Pismo, Fiserv (Optis, FirstVision), TSYS | The switch, the vault, the scheme connections, sold per card per month plus per transaction. Partners, not competitors: every one needs a system of record behind it, and Paymentology's Companion API is written for a client that “holds the customer's balance on your own platform”. Marqeta's programme-management tier is the exception: it will also hold the balance if asked, which is where a fintech ends up when it has no ledger. |
| Card management monoliths | OpenWay Way4, BPC SmartVista, Compass Plus TranzAxis, TSYS PRIME, CoreCard, ACI Postilion | Switch and card ledger in one box, licensed on-premise, the systems the big banks run. Broad, proven, and the reason the card account is separate from the customer's other accounts. We do not replace them; we are what a bank buys for a new programme it does not want to load onto them. |
| Core-attached modules | TCS BaNCS Cards, Oracle FLEXCUBE Card Management, Finacle via partners | A card module inside the core, sold on incumbency. Nearest to our shape, and the only population that can also say the card is in the customer's ledger. Wins where the bank already runs that core. |
| Modern cores | Temenos with Paymentology, Mambu with Paymentology, Thought Machine with Marqeta and Thredd, 10x, Tuum | Our technical peer group. All of them chose to partner for processing and keep the account in the core, which validates the shape; none of them, from their marketplace listings, has the card as a first-class aggregate with a cross-account funding rule. That is the seam to claim before one of them does. |
| Expense-card software | Pleo, Payhawk, Soldo, Spendesk, Moss, Brex, Ramp | Cards plus receipts plus approvals, on a BIN sponsor and an issuer processor, sold to corporates directly. They compete with the bank, not with us; a bank that can offer spend-controlled cards inside its corporate channel is the answer to them, and no core-attached module offers it. |
| Acquiring platforms | Way4, SmartVista, Fiserv Omnipay and Commerce Hub, Adyen and Stripe as full-stack | Merchant onboarding, dynamic pricing, settlement, reserves, disputes, in one box. The full-stack players own the gateway and the acquiring licence; the platforms sell to acquirers. Our shape is the second: the pricing and settlement engine an acquirer or a PSP runs behind its processor, which is exactly the [redacted] engagement. |
Where LedgerTM can actually win
Not on breadth, not on scheme coverage, and never on the switch. On five things we either already have or are unusually close to:
- The card inside the ledger. One customer, many accounts, one card, funding chosen per transaction rule. Demonstrable in two minutes, and structurally unavailable to a stand-alone card system.
- Value dating that is already right. Holds are claims and postings are cleared facts. The balance the customer sees is the balance the auditor sees.
- Configuration depth. A card product is an account type plus a card product row: a BIN, a scheme, a funding rule, controls, fees. A second programme is a YAML change. A merchant agreement is a row of parameters. The monoliths sell every one of those as a professional-services project.
- The price card from lived acquiring. The [redacted] engine was built once already, and the platform's pricing model descends from it. The attribute-banded price card is the generalisation, and it prices rail fees and card fees with the same mechanism.
- Event-sourced disputes. A chargeback here is a reversal in the stream with its own aggregate, not a case in a separate tool. “Show me exactly what we told the cardholder on day one and why we reversed it on day sixty” is a replay, not a search.
We have no card reference customer, no scheme relationship and no BIN sponsor. Every conversation will ask, and every one of those closes through a partner, not through code: Paymentology's partner programme exists precisely to connect a platform to sponsor banks, and a first prospect that already has a scheme membership is the cheapest path. And no processor publishes pricing, so the claim that a bank saves money by keeping the card in its ledger cannot be tested by desk research. It closes in a prospect conversation.
07Architecture
Eight subsystems, arranged so that no PAN ever crosses into the platform, the existing Account aggregate never learns that cards exist, and acquiring shares only the price card and the feed path with issuing.
The one modelling idea worth arguing about
The temptation is to make the card a property of the account: a card number on the current account, a status flag, a daily limit. Every stand-alone card system started that way, which is why a customer with two cards on one account, or one card across two accounts, is a special case in all of them.
The card is its own aggregate under the counterparty. ADR-314's placement rules say a concept with its own lifecycle leaves the container, and a card has one of the longest lifecycles in banking: it is ordered before it is active and it outlives the transactions it authorises by the length of the dispute window. It holds its credentials (plastic, virtual, device tokens), its controls, and a funding rule that names which account, or which ordered list of accounts, an authorisation draws on. The account never learns that cards exist: it sees a claim placed by the oracle and a posting from the feed, and both are ordinary.
Two subsidiary calls follow. The hold is a claim on the card, not on the account. An authorisation moves no money and appears in no ledger; it reduces available balance until an event or a date releases it, which is what the claim register was generalised to do (ADR-251). But a claim on the account is an event on the account's stream, released only by a day-end step, and every tap would then contend with the day-end walk that holds that stream. So the hold is appended to the card's own stream, releases in real time from the processor's reversal or the clearing match, expires by a day-end step over cards, and reaches the account through an inline projection keyed by account that sums every card's open holds. A transaction that is later “matched” to the hold is how the phantom-utilisation class of bug arrives (ADR-115's inversion exists because of it). The reserve is a claim, not an account. One claim per settlement day with a release date, consumed oldest-first by a chargeback, is a reserve that reconciles on the merchant statement without a reserve sub-ledger.
Card Products are configuration, and the current account is one type
An earlier reading suggested a retail current account separate from the corporate one. It should not be. A current account is a current account; what differs between a retail and a corporate tenant is the fee schedule, the interest, and whether an overdraft facility attaches, and every one of those is a property or a schedule on the type. One CurrentAccount type, promoted from the corporate package to the shared vocabulary, is the model. The overdraft is a facility attachment on the type plus one change to the withdrawal availability guard, both configuration: an account with no facility declines at zero, an account with one declines at the facility's limit. A clearing line ignores the guard (section 4.2), so a balance can still go past the limit, and that is the unarranged overdraft with its own fee and rate.
08The processor seam
Paymentology first, because it is the processor whose published integration model is the oracle model, and because it is South African born, global, and already the card partner of two cores in our peer group. The seam is designed so that a second processor is a second adapter, not a second design.
Why Paymentology
- Its Companion API is the oracle model, in its own words. The client “holds the customer's balance on your own platform” and “is responsible for authorizing transactions”. The alternative Card API keeps the balance at Paymentology and sends notifications after the fact. We design against the first and never the second.
- Visa, Mastercard and UnionPay on one integration; processing today for banks across Africa, the Middle East, Europe and Asia Pacific. Amex is not on its list, and Amex issuing outside Amex itself runs through Amex's own network licences: a second adapter, later, if a prospect insists.
- A partner programme built for platforms: it connects a platform to principal members who sponsor BINs, which is the commercial gap section 6 names.
- Already on the Temenos and Mambu marketplaces. A prospect comparing us to those cores sees the same processor on both sides of the table; the difference is what sits behind it.
- A published sandbox. The developer portal documents the card, tokenisation, provisioning and transaction-stream APIs, which is enough to write the simulator before a contract exists.
What we design against, and what we refuse
| Concern | Design |
|---|---|
| Which balance is true | Ours. The processor's transaction stream is a notification; its clearing file is a statement to reconcile; neither is the ledger. |
| Timeout | The oracle answers inside the processor's authorisation window or the processor stands in. The oracle is a read of a read model plus one claim append; it must never wait on a projection. |
| Idempotency | Every authorisation carries the processor's id; a repeat is answered identically from the stream, never re-evaluated. |
| Identity and tenancy | The processor calls with a per-tenant credential held in that tenant's settings. The adapter authenticates it at the edge, resolves the tenant, and dispatches inward as the System identity carrying that tenant, the service-token precedent of ADR-376 with a tenant added. The hold and posting commands are system commands; the clerk-facing card commands carry ordinary permission keys. One processor client and one BIN set per tenant; nothing shared. |
| Stand-in | A nightly push of card status and one conservative available balance per card: the available of the first account in its funding rule, never the sum of the list. The processor answers from it when we cannot; its approvals arrive as clearing lines with no hold and post unconditionally. The batch option, as a fallback only. |
| Reconciliation | The clearing feed matches holds to postings; an unmatched hold, an unmatched line, or a total that disagrees with the scheme's settlement advice is an exception item in Suspense. |
| A second processor | Same four contracts, a second adapter, a second simulator. A bank running Postilion in-house is that adapter against Postilion's host interface, built with that bank. |
09Sequencing
Four lanes, in an order chosen so that every lane ends with something a prospect can watch. Sizes are session estimates for the ledger side only; the processor contract and the BIN sponsor run in parallel on the commercial track and gate nothing here until the sandbox is replaced by production.
First — the seam, the card, the oracle: retail debit
Card aggregate and its credentials; the oracle with holds on the card, the inline per-account holds projection, real-time release, a day-end expiry step and a per-merchant-category expiry setting; the clearing-feed ingest matching holds to postings and posting unconditionally; CurrentAccount promoted to the shared vocabulary with the overdraft as a facility attachment and a guard change; the unarranged-overdraft fee and rate. About 7 sessions.Second — retail credit: the revolving product and issuer disputes
CreditCard type in a live retail package with sample data; correct the interest-free rule to evaluate at the due date and back-date accrual; payment allocation by highest rate; the revolving facility as the oracle's available; the issuer side of Disputes with provisional credit and clawback through ADR-261; card renewal at day-end; the attribute-banded price card, first used for card fees so that foreign-transaction and cash-advance fees vary by scheme, region and channel. About 5 sessions.Third — corporate: spend controls and virtual cards
Fourth — acquiring: the price card and merchant settlement
Merchant counterparty role with a merchant category; the merchant account type with net settlement at T+n; reserve claims with release dates and oldest-first consumption; payout by rail in the settlement currency; the acquiring side of Disputes. About 7 sessions.All four lanes, against the simulator; the acquiring feed is the simplest of them. The corporate proposal set the rule that every external system gets a simulator, and a processor is the easiest of them to simulate because its contracts are small and its sandbox is documented. What needs a bank is a BIN, a real scheme certification and a real bureau, which is to say production, not the product.
10Decisions taken
Taken in the discussion that produced this document, before any grill. Each is a design commitment the ADRs inherit unless the grill overturns it.
- The oracle, not batch. LedgerTM answers every authorisation in real time from its own available balance. Batch balance push survives only as the stand-in fallback.
- Cards inside retail. Debit and credit cards are retail products of the customer's ledger, which brings a shared
CurrentAccounttype and the first account type allowed below zero. - The switch is never ours. No ISO 8583, no scheme connection, no certification. The issuer's processor owns the switch; the acquirer's processor owns its own.
- No PAN, ever. A token reference, the BIN and the last four. Enforced by a build-time test over every contract and read model, so PCI DSS scope stays with the processor.
- Paymentology first, against its Companion API shape. A second processor is a second adapter behind the same four contracts.
- The card is an aggregate under the counterparty, with a funding rule. Never a property of an account.
- The hold lives on the card; the reserve is a claim on the merchant account. Neither is a transaction. The card's holds reach the account through an inline projection keyed by account; the reserve reuses ADR-251 with a new origin.
- The funding rule is an ordered list, whole amount, no split. All entries share the card's billing currency; an overdraft is the facility on the current account, not an entry; a credit card's list has one entry.
- A clearing line posts unconditionally. Past the guard, past the facility, into an unarranged overdraft with a configured fee and rate. Stand-in approvals arrive the same way.
- Provisional credit is a tenant rule per reason-code class. Fraud and unauthorised use credit on day one; merchandise and service disputes credit on outcome.
- The processor is a per-tenant credential dispatched as the System identity. ADR-376's service token with a tenant added.
- The scheme is vocabulary. Visa, Mastercard, UnionPay, a wallet, an alternative payment method: a row on the product and on the price card, never a branch in code.
- The clearing file is the ledger's source; the real-time stream is a notification. Reconciliation runs feed against holds, daily, into Suspense.
- Fraud scoring stays with the processor. The oracle applies the bank's and the customer's rules, not a risk model.
- We build no gateway and no expense-management tool. Website plug-ins belong to the gateway vendors; receipts and approvals belong to the SaaS vendors.
- Retail debit leads, credit second, corporate third, acquiring last. The three issuing lanes build on each other; acquiring is a separate column and waits for its own buyer.
One pair looks contradictory and is not
Decision 12 puts acquiring last; section 2 says it is the product we have already delivered once. Both are true. Acquiring is a separate column of the architecture sharing one boundary and one price card with issuing, so nothing in the issuing lanes waits for it, and it has no bank customer to ride in on. It is last by sales path, not by readiness. The price card it needs is built in the credit lane for card fees, so the acquiring lane starts shorter than its estimate.
11The ADR series this seeds
Numbers come from GitHub issues at design time (ADR-425); names and shapes are proposed here. Each is a correctness ADR with scenarios unless marked.
Card Connectivity — the processor seam
- The processor contracts and the Paymentology simulator. The four contracts, the adapter, the simulator, the no-PAN build test, tenant scoping. Nothing above this can start.
- The clearing feed as a statement. The card attribute model on a feed line, ingest through
FormatProfile, hold matching, exception items to Suspense.
Cards and Authorisation
- The card aggregate and its credentials. Lifecycle, plastic and virtual and device credentials, controls, the funding rule.
- The authorisation oracle and the card hold. The check order, reason codes, partial approval, the hold on the card with a merchant-category expiry, the inline per-account holds projection, real-time release and day-end expiry, idempotency, the timeout rule.
- The current account, the overdraft facility and the unconditional clearing post.
CurrentAccountto the shared vocabulary; the facility attachment and the guard change; the clearing line as a posting source that outranks the guard; the unarranged overdraft's fee and rate.
Card Products
- The revolving credit card, corrected. The dormant template into a live package; the interest-free rule at the due date with one catch-up posting per cycle and the day-weighted purchase function it needs; allocation by highest rate; the revolving facility as available. Mechanical where it is configuration, correctness where the accrual rule changes.
- Card renewal and replacement at day-end. A day-end step; fees by configuration.
Disputes
- The dispute aggregate. One per disputed transaction, scheme stages and clocks, evidence references, provisional credit as a tenant rule per reason-code class, clawback through ADR-261 including any catch-up interest the purchase carried, case fees. Both sides, linked by the scheme case reference when the merchant is on-us.
Transaction Pricing and Merchant Settlement
- The attribute-banded price card. A price chosen by scheme, region, card type, channel, currency and amount band, effective-dated, with per-merchant plans; the row hit is stored on the priced transaction. Absorbs rail fees (ADR-416) so one mechanism prices everything.
- The merchant and the merchant account. The merchant role with a category, the settlement account type, net settlement at T+n, settlement currency and FX at payout.
- The rolling reserve as claims. One claim per settlement day, percentage and target rules, release at day-end, oldest-first consumption by a chargeback, the dispute-ratio step-up.
Spend Controls
- Corporate card controls and just-in-time funding. Ceilings, category and merchant rules, the pooled funding rule, single-use credentials, and the two client-channel operations for the corporate administrator.
12Changed during the grill
This document was written, then adversarially interrogated against the codebase on 29 September 2026 before being circulated. What the draft said, what it says now, and why.
- The hold moved from the account to the card. The draft said “the hold is a claim” as if reuse of ADR-251 were free. The code says a claim is an event on the account's own stream, released only by a day-end step; every tap would have contended with the day-end walk that holds that stream, and a merchant reversal at 14:00 would have waited for midnight. The hold now lives on the card's stream, releases in real time, expires by a day-end step over cards, and reaches the account through an inline projection keyed by account. Sections 4.1, 4.3, 7, 9 and 10.
- “No account type may go below zero” was wrong. Nothing in the aggregate refuses a negative balance; withdrawals are refused by an availability guard expression on the operation, per account type. The overdraft is a facility attachment plus a guard change, both configuration, and the estimate for lane one fell accordingly before the next item raised it again. Sections 2, 3.1, 7.
- The funding rule was pinned: an ordered list, whole amount, never split. The draft offered “one account, or an ordered list” and section 12 admitted it did not know. Splitting a hold across accounts was rejected because it produces two postings for one receipt; an expression was rejected because it is unbounded inside an authorisation timeout and unreadable to a clerk explaining a decline. A credit card's list has one entry so one walk serves both products. Sections 4.2, 10.
- The clearing line posts unconditionally. The draft never said what happens when a tip, an offline transaction or a late clearing exceeds the account's available. It now posts past the guard and past the facility into an unarranged overdraft with a configured fee and rate, because the bank has already paid the scheme. Parking the shortfall in suspense was rejected as hiding a payment the bank made. Sections 4.2, 7, 10.
- Hotel example corrected. The worked example gave a hotel hold the general seven-day expiry while the rule beside it said thirty for hotels and car hire. Now thirty. Section 4.1.
- Catch-up interest is one posting per cycle, not one per purchase, and the mode after it is stated: purchases accrue daily from their transaction date until a statement is again paid in full. The draft's worked example and its rule disagreed on the count and never named the mode. It needs one new expression function, a day-weighted sum over the cycle's purchases. Sections 3.2, 11.
- The acquiring GL sentence contradicted itself. The draft said the net posts to the merchant account at T+n and, two lines on, that GL moves only on payout. The T+n posting is a ledger posting and moves GL into the merchant payable; it is the reserve that moves nothing, because the payable already carries the money. Section 4.6.
- A corporate card's owner was unstated. It sits under the corporate counterparty; the employee is a named cardholder, not the owner; a funding rule may only name accounts the owning counterparty holds or services (ADR-327). Section 3.3.
- Currency at authorisation was decided nowhere. The processor converts to the card's billing currency before the message reaches us; every account in a funding rule shares that currency; the original amount travels with the clearing line for the statement. Section 4.2.
- Provisional credit became a rule per reason-code class rather than a single tenant switch, because PSD2's next-business-day refund applies to unauthorised use and not to a quality dispute. A won dispute against a purchase that already carried catch-up interest reverses that interest's share; the interest-free flag is never re-decided retroactively. On-us disputes run as two linked aggregates with the scheme as arbiter. Sections 4.5, 5, 10.
- The processor's identity was unstated. A per-tenant credential in settings, authenticated at the edge, dispatched inward as the System identity carrying the tenant: ADR-376's service token with a tenant added. Stand-in pushes the available of the first funding-rule account only. Sections 8, 10.
- Lane one grew from six sessions to seven for the projection, the expiry step and the unarranged overdraft. Section 9.
Pressed and held without change: the oracle over batch; cards inside retail; the switch and the PAN staying with the processor; Paymentology first against its Companion API shape; fraud scoring at the processor, with the customer's and the bank's rules in the oracle; no gateway and no expense-management tool; the reserve as one claim per settlement day; one CurrentAccount type for retail and corporate; the price card as the one pricing mechanism, absorbing ADR-416's rail fee amounts while the rail fee keeps its transaction type and charge bearer.
There is no buyer. This is speculative work, which is the platform's stated posture: build the generic concept properly for a customer we do not have yet. The sequencing is therefore chosen by what can be demonstrated soonest, not by a named prospect, and the acquiring lane starts when the issuing lanes have shipped, not when a PSP calls.
Contradiction press: 10 pairs, resolved as the hotel expiry, the catch-up count and mode, the acquiring GL sentence, the corporate card's owner, the unarranged overdraft past an existing facility, the credit card's single-entry funding rule, on-us disputes as two linked aggregates, currency at authorisation, interest recompute after a reversed purchase, and the stand-in balance as the first account's available. Each is folded into the section named above. The press was run by a fresh agent given only the decisions and the worked examples.
Deferred, with an owner and a date
- Which Paymentology platform a bank credit programme sits on. The Companion API is documented on the Sprint portal, the prepaid and fintech platform; a bank programme may sit on the enterprise platform with a different surface. The adapter is designed against the Companion shape. Jeremy confirms at the first Paymentology conversation, by end of October 2026; a different surface changes the adapter, not the design.
- Amex and the third-party schemes. Not on Paymentology. A declared gap for the first customer; a second adapter when a prospect insists.
- The oracle's timing under a day-end walk. With holds on the card and inline read models for the account and the facility, the read is two documents and one append. It still wants a measurement, not an opinion, in lane one's first bite.