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-840: Cards and Authorisation: disputes and chargebacks

Status: Shipped — 2026-10-03


Context

The Problem

A cardholder who does not recognise a purchase, never received the goods, or was charged twice disputes it. The scheme’s machine for that — a chargeback with a reason code, the merchant’s representment, pre-arbitration, arbitration, each with a clock — runs through the processor into Visa Resolve Online or Mastercom. The stand-alone card systems keep that machine in a case-management tool outside the ledger; the auditor reconstructing who credited whom, when, and on whose evidence has to read two systems.

Today the platform records nothing. ADR-836’s clearing post records a Chargeback line as an exception on the batch (CHARGEBACK_NOT_HANDLED) for this ADR; nothing raises a dispute, credits a cardholder provisionally, claws that credit back, or charges a case fee.

What Already Exists

Scope

This ADR covers:

Out of scope: the acquiring side (the merchant settlement ADR: the chargeback in the feed, the reserve, the merchant’s evidence), an on-us short cut when the merchant is the tenant’s own acquiring customer (the two sides run as two aggregates linked by the scheme case reference, the scheme the arbiter), retrieval requests as a stage of their own (recorded as a note when the processor reports one), fraud detection, and the customer raising a dispute from the client channel (ADR-695’s operation list, a later item).


Decisions

1. A dispute is an aggregate of its own, one per disputed transaction

CardDispute lives in LedgerTM.Cards with its own id (many per card, ADR-314): the card, the funding account the purchase posted to, the posting’s transaction id and the clearing line’s processor reference, the amount and currency disputed (the whole line or part of it, never more than the line less refunds already posted against it), the reason code (a vocabulary row, Decision 2), the stage, the date each stage was entered and the date the next move is due, the evidence references, the scheme’s case reference once the processor has one, the provisional credit’s transaction id if one was posted, and the outcome. One dispute may be open per transaction at a time; a second portion of the line waits for the first to close. A dispute is raised on the principal posting a clearing line made — a purchase or a cash advance, never a refund, a reversal or a chargeback, and never a posting that no clearing line made — whatever the card’s status, since fraud sits on lost and closed cards. It is refused once the reason code’s filing limit, counted inclusively from the line’s transaction date, has passed, whether it is the first on the line or a later one; and after a dispute lost or withdrawn under the same reason code. The refunds that reduce what may be disputed are the scheme’s reversals matched to the line by authorisation and earlier won disputes on it; a merchant’s own refund names no purchase and reduces nothing. A cash-advance fee is the bank’s charge, not the line, and is never part of the dispute. The ledger knows which posting a line made because the clearing post keeps an index of its postings — card, token, line reference, authorisation, kind, amounts in both currencies, transaction date — which the raise reads, and which the scheme’s reversals update.

2. Reason codes are a vocabulary with a category, a credit rule and clocks

CardDisputeReasonCodeSettings carries one row per scheme reason code the tenant files under: the scheme, the code, a label, its category — the schemes’ word — (Fraud, Authorisation, ProcessingError, ConsumerDispute), the provisional-credit rule (OnRaise: the customer is credited when the dispute is raised; OnOutcome: the customer is credited when it is won, and nothing posts before), the filing limit in calendar days from the line’s transaction date (the limit day inside it; the schemes count from their processing date, a day or two later, so ours is the earlier and safer bound), and a response window in calendar days for each contested stage — the merchant’s to represent, the bank’s to concede or escalate, the merchant’s at pre-arbitration, the scheme’s at arbitration. The retail template seeds a starter set — Visa’s four categories (10 fraud, 11 authorisation, 12 processing error, 13 consumer dispute) and two of Mastercard’s 48xx codes — with the credit rule OnRaise for fraud and unauthorised-use codes and OnOutcome for the rest, as the practice has it and as PSD2 Article 73 requires of an EU tenant. The row carries a typed id (ADR-422), slug-derived from the scheme and the code, and its key must be that slug; the dispute holds the id.

3. The stages are the scheme’s, and the processor moves most of them

Raised → Represented → PreArbitration → Arbitration → Closed, closed as Won, Lost, MerchantAccepted (the merchant conceded; the money moves as for Won) or Withdrawn. The bank raises, escalates a representment to pre-arbitration, concedes to the merchant’s evidence (the dispute closes Lost, with no case fee — Concede, never Accept, so one word cannot mean a win on the outcome and a loss on the verb), or withdraws; the processor reports the merchant’s representment, the merchant’s refusal at pre-arbitration (which is what moves the dispute to Arbitration), the scheme’s case reference and the arbitration’s ruling through one inbound door, CardDisputeUpdate, with a receipt as every door has. Every transition is an event on the dispute’s stream carrying the user who moved it or the update reference the processor sent. The bank’s own calls are synchronous: the processor’s answer to the call is its word, and the dispute moves at once; a refusal is the processor’s refusal code, as ADR-835 has it. The bank withdraws from any open stage; the processor is told, and a case the merchant has made stands as the end of it. An update naming a stage the dispute has passed, or a dispute the ledger never raised, is answered by its receipt and moves nothing. A dispute closes only on the processor’s word — its answer to a call or its update — never on a clock. An update that skips a stage is applied as reported, since the scheme may; one that repeats the current stage with a new reference records the reference; Closed without an outcome, or an outcome on an open stage, is refused. A stage is entered on the date the update carries; the trading date it arrived is recorded beside it.

4. The clocks are watched at day-end

Each stage entered sets the date the next move is due from the reason code’s window. A day-end step at order 47, CardDisputeDeadlinesStep, non-critical, behind cards.disputes, raises a follow-up task to the disputes group when a due date on a window that is the bank’s to act in is within the tenant’s warning days (CardDisputeSettings.WarnDaysBeforeDeadline, default 5) — one task per due date, none for a window the merchant or the scheme owns, since a lapse there is the cardholder’s win — and marks the dispute Overdue the day after it passes. The step never closes a dispute; Overdue clears when the stage moves, and the bank may still act after its window, the processor deciding whether the scheme accepts it. A window the merchant lets lapse — to represent, or to answer at pre-arbitration — is the cardholder’s win; a window the bank lets lapse — to concede or escalate a representment — is the merchant’s; the processor reports either as the close, and the dispute records it as it records every other outcome. The clocks are calendar days, as the schemes count them.

5. Provisional credit is a system posting on the funding account, timed by the rule

There is one dispute credit, and it is value-dated as the purchase. When the reason code’s rule is OnRaise, raising the dispute posts ProcessCardDisputeCreditCommand to the account the purchase posted to, through the account type’s cardDisputeCredit integration, as the type’s dispute-credit rows — the customer’s balance back up, the bank’s chargeback receivable from the scheme on the other leg — value-dated the purchase’s value date, which is what PSD2 Article 73 asks (a refund value-dated no later than the debit) and what makes a credit card’s deferred and catch-up interest on the disputed amount re-walk to nothing at once (ADR-837’s revaluation cascade, ADR-838 D6). When the rule is OnOutcome, the same credit posts when the dispute closes Won or MerchantAccepted. Nothing else is ever credited: a won dispute whose credit already posted posts nothing further, and the credit is final. The amount is the amount disputed, in the account’s currency as the clearing line posted it; the processor is told the scheme’s amount in the line’s original currency — the remaining original amount for a whole remainder, prorated and rounded to the original currency’s ISO 4217 minor unit for a part. The command carries the line’s merchant category, name and country as the refund command does, so on a credit card the type’s own workflow decides purchase against cash advance by merchant category — one rule, in the YAML, never a second in Cards — and posts fixed legs: on the purchase’s own value date the amount is wholly in that cycle, so no split against today’s balances is needed. Where the customer had already paid, the purchase balance replays negative, which ADR-838’s available figure counts as a credit. If the funding account is not active, the credit cannot post: the dispute records it as forgone, a task goes to the disputes group, and the dispute proceeds.

6. The outcome moves the money through two postings

7. Evidence is referenced, not stored

A dispute records what the bank submitted or received: a description, the date, who added it, and a reference — the Attachments feature’s AttachmentId for a file the bank holds (moved to Contracts so the reference is typed), or the processor’s own reference for what the merchant sent. The reference is recorded, not validated, and evidence may be added while the dispute is open. The processor holds the submission; the dispute holds the trail.

8. The processor seam, both ways

ICardProcessor gains RaiseDisputeAsync, EscalateDisputeAsync, ConcedeDisputeAsync, WithdrawDisputeAsync and SubmitDisputeEvidenceAsync; the Paymentology adapter maps them to its dispute API and the simulator plays the scheme on the trading-date clock: a raised dispute is represented halfway through the merchant’s window with scripted evidence, the merchant holds its ground halfway through pre-arbitration, and arbitration rules halfway through its window by a simulated rule the demo tenant sets (CardProcessorSettings.SimulatedDisputeOutcome: Won, Lost, or ByAmountParity — an amount whose whole currency units are even wins, odd loses; 12 000 wins, 12 001 loses), so a prospect can watch both paths. The simulation is a step of its own behind RequiresSimulation, as the clearing simulation is, and reports through the real door. A lapse is never simulated; the tests drive it through the stub.

9. Permissions, four-eyes and the screens

Raising, escalating, conceding and withdrawing a dispute are user commands on the dispute (a Raise on the card’s transaction), four-eyes eligible and reviewable: the dispute registers a CardDisputeApproverViewReader and is a SelfHoldingAggregate. Recording evidence is INotFourEyesGated (a note, no money). The door’s update, the credit, the clawback, the fee and the deadlines step are system commands; the money is cascaded from the committed stage event by one Cards system command, which checks the funding account is active before posting and records the posting or its forgoing, so a credit never stands without its dispute. A raise answers the new dispute’s id, or the capture answer every four-eyes command gives; the ordinal is taken when the raise executes, so an approved capture never collides. Disputes sit behind a feature key of their own, cards.disputes, a child of cards.issuing, so a tenant that leaves disputes to its processor switches the screens and the step off in one act. The card viewer gains a Disputes panel; the account’s transaction history offers Dispute on a card posting; a dispute has a viewer of its own (route:/card-disputes/{id}) showing the stage, the clock, the evidence and the money moved.


Contracts

Ids — CardDisputeId (LedgerTM.Contracts/Cards); CardDisputeReasonCodeId (a vocabulary row id, slug-derived from {scheme}-{code}).

Commands — RaiseCardDisputeCommand, EscalateCardDisputeCommand, ConcedeCardDisputeCommand, WithdrawCardDisputeCommand, RecordCardDisputeEvidenceCommand (LedgerTM.Cards, ICommand); RecordCardDisputeUpdateCommand (the door, IExternallyAuthenticatedCommand); WatchCardDisputeDeadlinesCommand, SimulateCardDisputesCommand (the steps’), PostCardDisputeMoneyCommand (the cascade, ISystemCommand); ProcessCardDisputeCreditCommand, ProcessCardDisputeClawbackCommand (LedgerTM.Contracts/Accounts, ISystemCommand, beside the card postings); RequestCardDisputeFollowUpTaskCommand (LedgerTM.Contracts/Tasks, ISystemCommand); AmendCardDisputeReasonCodesCommand, AmendCardDisputeSettingsCommand (settings commands).

Events — on the dispute’s stream: CardDisputeRaised, CardDisputeRepresented, CardDisputeEscalated, CardDisputeEvidenceRecorded, CardDisputeCaseReferenceRecorded, CardDisputeOverdue, CardDisputeClosed (with the outcome, the user or update reference, and a withdrawal’s reason), CardDisputeCreditPosted, CardDisputeClawbackPosted, CardDisputeFeeCharged, CardDisputeSettlementRecorded, CardDisputePostingForgone.

Queries — GetCardDisputeQuery, ListCardDisputesForCardQuery, GetCardDisputeReasonCodesQuery, GetCardDisputeSettingsQuery (IQuery<T>).

Consumed from LedgerTM.Cards — ICardProcessor, CardClearingItem. Each lived in Contracts when this ADR shipped, and moved to its only reader on 2026-10-21 (ADR-755 ruling). Consumed from LedgerTM.Contracts — ProcessCardPurchaseCommand (the shape), ProcessCardFeeCommand (ADR-839).

Changed — ICardProcessor gains the five dispute calls; CardProcessorSettings gains SimulatedDisputeOutcome; ExternalIntegrations gains CardDisputeCredit and CardDisputeClawback; TransactionSource gains both; CardClearingItem gains a nullable DisputeReference; AttachmentId moves to LedgerTM.Contracts; ADR-836’s clearing post records a Chargeback line on the dispute it names instead of recording an exception, and writes the posting index.

Supporting shapes (the plan’s ## Interfaces, F3) — CardDisputeStage, CardDisputeOutcome, CardDisputeCategory, ProvisionalCreditRule, CardDisputePostingKind, EvidenceSource, CardDisputeRequest, CardDisputeReference, CardDisputeEvidence, CardDisputeUpdate (LedgerTM.Contracts/Cards); the door’s CardDisputeUpdateId, CardDisputeUpdateOutcome and CardDisputeUpdateReceipt beside the other receipts; CardDisputeTaskPurpose beside the task command.

Also changed — FeatureCatalog gains cards.disputes; IGroupPermissionsReader gains GroupExists, which the disputes-group check reads; ProcessCardRefundCommand is unchanged, its file gaining the two dispute postings beside it.

Removed — none.


Prior art

Declared Search returned Verdict
CardDispute, CardDisputeId Card (ADR-835), DefaultProcess (ADR-302, a staged per-account aggregate), SuspenseCase genuinely new — a concept with its own lifecycle under the card (ADR-314 D3); no case aggregate exists for a card
CardDisputeReasonCodeSettings, CardDisputeReasonCodeId CardTypesSettings (ADR-835), CardHoldExpirySettings (ADR-836), OutcomeCatalogSettings extend — a vocabulary settings class with typed rows, the ADR-422 shape
CardDisputeSettings CardProcessorSettings (a facet), CollectionSettings genuinely new — the tenant’s warning days and disputes group; a facet is the wrong home for a product rule
RaiseCardDisputeCommand, EscalateCardDisputeCommand, ConcedeCardDisputeCommand, WithdrawCardDisputeCommand, RecordCardDisputeEvidenceCommand SuspendCardCommand, ReissueCardCommand (ADR-835 verbs) extend — the dispute’s verbs in the card verbs’ shape
RecordCardDisputeUpdateCommand ReverseCardAuthorisationCommand (an inbound door with a receipt) extend — a third door
CardDisputeDeadlinesStep, WatchCardDisputeDeadlinesCommand RenewCardCredentialsStep (ADR-839, 46), ExpireCardHoldsStep (ADR-836, 45) extend — order 47; the simulation step at 48
ProcessCardDisputeCreditCommand, ProcessCardDisputeClawbackCommand, CardDisputeCredit, CardDisputeClawback ProcessCardRefundCommand (ADR-836), ProcessCardFeeCommand (ADR-839) extend — the refund command’s shape with the merchant fields; a refund’s GL leg is the settlement payable, a dispute credit’s the chargeback receivable, so they are their own types
PostCardDisputeMoneyCommand ChargeCardFeeCommand (ADR-839, a cascaded Cards system command recording posted or forgone) extend — the same shape for the dispute’s postings
SimulateCardDisputesCommand SimulateCardClearingFileCommand (ADR-836, a RequiresSimulation step) extend — the same shape
GetCardDisputeReasonCodesQuery, GetCardDisputeSettingsQuery, GetCardDisputeQuery, ListCardDisputesForCardQuery GetCardTypesQuery, GetCardProcessorQuery (ADR-835) extend — settings reads in the same shape
AttachmentId LedgerTM.Attachments’ own id reuse — moved to Contracts so an evidence reference is typed
RequestCardDisputeFollowUpTaskCommand RequestSuspenseCaseFollowUpTaskCommand, RequestAccountFollowUpTaskCommand extend — the same shape for a dispute
card-dispute-fee card-replacement-fee (ADR-839) extend — a price row
CardProcessorSettings.SimulatedDisputeOutcome SimulatedCredentialLifeMonths (ADR-839) extend — a facet field the simulator alone reads
AmendCardDisputeReasonCodesCommand, AmendCardDisputeSettingsCommand AmendCardTypesCommand, AmendCardProcessorCommand (ADR-835’s settings commands) extend — settings commands in the same shape
CardDisputeRaised, CardDisputeRepresented, CardDisputeEscalated, CardDisputeEvidenceRecorded, CardDisputeCaseReferenceRecorded, CardDisputeOverdue, CardDisputeClosed, CardDisputeCreditPosted, CardDisputeClawbackPosted, CardDisputeFeeCharged, CardDisputeSettlementRecorded, CardDisputePostingForgone (events) CardHoldPlaced, CardHoldReleased (ADR-836), CardFeeForgone (ADR-839) genuinely new — the dispute’s own stream; no event records a stage
CardDisputeStage, CardDisputeOutcome, CardDisputeCategory, ProvisionalCreditRule, CardDisputePostingKind, EvidenceSource, CardDisputeRequest, CardDisputeReference, CardDisputeEvidence, CardDisputeUpdate, CardDisputeUpdateId, CardDisputeUpdateOutcome, CardDisputeUpdateReceipt, CardDisputeTaskPurpose DeviceProvisioningRule, CardReceiptOutcome, CardReversalReceipt, CardAuthorisationRequest (ADR-820, ADR-835) genuinely new — the dispute’s own vocabulary and the processor’s dispute shapes, in the card seam’s shape: a rule enum beside the card type’s, a receipt beside the doors’ receipts
ICardProcessor, CardClearingItem, ProcessCardPurchaseCommand ADR-820 and ADR-836 reuse — the seam gains five calls (extend); the clearing line and the purchase posting are read as they are

Relies on

Symbol What it does today What this ADR assumes
ICardProcessor Create, reissue, status, controls, plastic, close, reveal, clearing file Gains the dispute calls (D8)
CardClearingItem A clearing line with its kind, amounts, merchant and processor reference Gains a nullable dispute reference a Chargeback line carries (D6)
RequestSuspenseCaseFollowUpTaskCommand A follow-up task with a due date to a group The deadline task follows its shape (D4)
SelfHoldingAggregate An aggregate that holds its own change set for review (ADR-780) The dispute is one (D9)
IDayEndStep A step with an order, a phase and a criticality The deadlines step at 47 (D4)

ADR-836’s ProcessCardPurchaseCommand and its clearing post, ADR-838’s deferred-interest rows and ADR-839’s ProcessCardFeeCommand are relied on as their plans declare them.


Worked example

Fixture: the simulated tenant, the demo customer’s credit card (ADR-838) with a 12 000 purchase posted 2026-09-10 from a merchant the customer does not recognise; reason code Visa 10.4 (fraud, card-absent), rule OnRaise, a 30-day window at the three contested stages and 45 at arbitration; card-dispute-fee 250; simulated outcome ByAmountParity; the credit card’s grace-status row marked onRevaluation: KeepHigher.

Date Act Dispute Account
2026-09-20 the clerk raises the dispute on the posting for 12 000 Raised, due 2026-10-20; the processor answers a case reference PurchaseDisputeCredit 12 000 value-dated 2026-09-10: purchases and cycle purchases down to 0, chargeback receivable up; September’s deferred interest on the 12 000 re-walks to nothing; the grace status stands
2026-09-21 the clearing file carries the first chargeback cycle settlement 12 000 recorded; stage unchanged —
2026-10-05 the simulator represents with the merchant’s evidence, halfway through the window Represented, due 2026-11-04; a task to the disputes group on 2026-10-30 —
2026-10-06 the clerk escalates PreArbitration, due 2026-11-05 —
2026-10-21 the simulator reports the merchant holds its ground Arbitration, due 2026-12-05; the scheme’s case reference recorded —
2026-11-12 the simulator rules: 12 000 is even, the cardholder wins Closed, Won nothing: the credit of 2026-09-20 is final
— had the amount been 12 001 Closed, Lost PurchaseDisputeClawback 12 001 value-dated 2026-11-12, in November’s cycle; card-dispute-fee 250 posts through ADR-839
— had the code been Visa 13.1 (OnOutcome) as above nothing at the raise; the won credit value-dated 2026-09-10 on 2026-11-12, re-walking the interest then

Had the merchant not represented by 2026-10-20, the dispute reads Overdue from the 21st, the processor reports the cardholder’s win, and it closes Won without a hearing. Had the clerk neither conceded nor escalated by 2026-11-04, the processor reports the merchant’s win and it closes Lost — the clawback, no case fee.


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 CardDisputeClawback {
    <<new>>
  }
  class CardDisputeCredit {
    <<new>>
  }
  class Chargeback {
    <<new>>
  }
  class DisputeReference {
    <<new>>
  }
  class GroupExists {
    <<new>>
  }
  class CardClearingItem {
    <<relies-on>>
  }
  class ICardProcessor {
    <<relies-on>>
  }
  class IDayEndStep {
    <<relies-on>>
  }
  class RequestSuspenseCaseFollowUpTaskCommand {
    <<relies-on>>
  }
  class SelfHoldingAggregate {
    <<relies-on>>
  }

Consequences

Positive

Negative / Trade-offs

Neutral


Implementation Plan (Bites)

Six bites, one land; reseed: true. Bite 1 can start now; bites 2, 3, 5 and 6 after ADR-836 lands; bite 4 after ADR-838 and ADR-839 too. Bites, acceptance criteria, files touched, and status live in ADR-840-plan.md.


Changed during the grill

Grilled 2026-10-02 by the author against ADR-835, ADR-836, ADR-838, ADR-839 and the press; the operator’s standing instruction was to take the recommendations.

Contradiction press: 12 pairs, resolved as above — 1, 5, 9 and 12 into Decision 4; 2 and 4 into Decisions 5 and 6; 3, 8 and 10 into Decision 1; 6 and 7 into the example and Decision 2; 11 into Decision 3. The four silent inputs (a cash advance, a closed funding account, an unknown dispute, a chargeback line on a closed dispute) are answered in Decisions 1, 6, 3 and 6.

Press block
  1. Overdue representment: D4 said the merchant’s win, the example the cardholder’s.
  2. OnOutcome at Won: D5 posts a credit, D6 reverses one that was never posted.
  3. One open dispute per transaction vs a partial dispute.
  4. The clawback assumed a credit exists under Never.
  5. Bank-side overdue unstated.
  6. The example skipped Arbitration.
  7. One window vs per-stage windows.
  8. The filing limit unstated for the first raise.
  9. Processor update vs day-end auto-close race.
  10. Double reversal on a partially refunded purchase.
  11. Withdrawal after representment.
  12. A zero-day window.

Phase A (acceptance-test author, 39 questions), 2026-10-02. The rulings that changed a decision:

Changed during the plan grill

Grilled 2026-10-02 on the plan’s signatures and mapping (ADR-692 D23); twenty press points, rulings taken on the operator’s standing instruction.

Pressed and held: generated CardDisputeId with the ordinal invariant; slug-derived reason-code ids; processor and scheme references as strings (house precedent); the markers; the door’s authentication; evidence INotFourEyesGated; per-tenant settings; derived posting ids; calendar days; every scenario in LedgerTM.Tests.Component with one method each.

Changed during phase B

Six acceptance-test authors wrote 56 cold tests on 2026-10-02 (docs/adr/ADR-840-tests/). Their findings, folded:

Notes

Outcome

Landed as designed across six bites: a card dispute on its own stream with the scheme’s stages, the processor’s update door with receipts, the simulated scheme ruling by whole-unit parity, the one-message close cascade (credit value-dated as the purchase, clawback today, a lost arbitration’s fee), the deadlines step and the screens. Three choices differ from the plan, each logged in its landing notes: the raise targets the funding account for review, the per-transaction document gave way to a read over the summaries, and no sample dispute is seeded because no seed posts a card purchase (F-1874).