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
- The card (ADR-835), the hold and the clearing post with the merchant on every posting (ADR-836), the current account and the credit card the posting lands on (ADR-837, ADR-838), and the card fee (ADR-839).
- ADR-261: a back-dated reversal takes the original’s value date and cascades
RevalueAccount, so interest re-walks;PostTransactionReversalCommandis the system path. - The processor seam (ADR-820): outbound calls on
ICardProcessor, inbound doors with receipts (DecideCardAuthorisation,ReverseCardAuthorisation), the simulator playing the processor. - Tasks (
Request*FollowUpTaskCommand) with a due date; the Attachments feature’s files and notes; a per-account staged aggregate on its own clock (ADR-302’s default process). - ADR-422: a vocabulary row with a typed id; ADR-780: reviewability through an approver view reader and a holder.
Scope
This ADR covers:
CardDispute, one per disputed transaction, with the scheme’s stages, the reason code, the clocks, the evidence references and the outcome — the issuer side.- The reason codes as a vocabulary, each with its category, its provisional-credit rule and its time limits.
- The dispute credit, value-dated as the purchase, and its clawback as system postings; the case fee through ADR-839.
- The processor seam for a dispute, both ways, and the simulator playing the scheme.
- A day-end step that watches the clocks.
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
- Won or accepted by the merchant: under
OnOutcomethe dispute credit posts now (Decision 5); underOnRaiseit posted at the raise and is final. The purchase is never reversed: ADR-261’s reversal undoes a whole posting and every leg of it at the original’s value date, a dispute may be for part of a line, and a credit card’s provisional credit is several legs of which a reversal by id would undo one. AChargebackclearing line (ADR-836), matched to its dispute by the processor’s dispute reference the line now carries, is the scheme’s movement of the money — the first chargeback cycle, a day after the raise, as often as the outcome — so it is recorded on the dispute with its amount and never moves the stage; the dispute closes only on the processor’s word (Decision 3). The chargeback receivable clears against the scheme’s settlement, which the merchant settlement ADR owns. - Lost or withdrawn: a dispute credit, where one was posted, is clawed back by a new debit
posting through
ProcessCardDisputeClawbackCommand, value-dated today — a new transaction in today’s cycle, as the schemes and Regulation E re-debit, so a credit card’s statement and grace stand as the customer saw them and nothing re-walks. A lost arbitration chargescard-dispute-feethrough ADR-839’s card fee, on the dispute’s own funding account. A withdrawal charges nothing. - A dispute posting that cannot post — the funding account is not active when the credit or the clawback is due — is recorded on the dispute as forgone with its kind and amount, and a task goes to the disputes group; the dispute proceeds. The case fee is one such posting: the dispute records it forgone at the price row’s amount, and records a fee only when it posted. A clawback and a fee forgone on one day share one task naming both. “Not active” is what the account availability reader answers (ADR-836): a frozen account forgoes too, which is the conservative side for a re-debit.
- A re-walk may restore the interest-free period and never take it away. A re-walk after a
back-dated dispute credit re-evaluates every amount row, the statement’s
Setrows included, so the deferred interest on the disputed purchase re-walks to nothing. The credit card’s grace-status row is markedonRevaluation: KeepHigher: the re-walk keeps the higher of the value it recorded and the value it now computes, so a customer who lost the interest-free period only because of the disputed purchase gets it back — PSD2 Article 73 restores the account to the state it would have been in — while a re-walk can never remove a grace the due date granted (ADR-838 D6). The flag is the engine’s, generic configuration on anySetrow (Reevaluate,AsRecorded,KeepHigher,KeepLower; a replayed row replays its day’s recorded outcome, including nothing); this ADR adds it, with a unit test written first, and the template load refuses it on any row but aSet. The re-walk of an external posting itself is ADR-837’s cascade (its bite 5), a dependency.
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
- The auditor’s trail is in the ledger: stage, reason, deadline, evidence, money moved, on one stream, replayable.
- Provisional credit is a rule, not a judgement call, and it is the PSD2 rule where that applies.
- The money moves through two postings and what exists: the dispute credit and its clawback as workflow rows, ADR-839’s fee, ADR-837’s re-walk. Nothing is reversed.
- The demo shows both outcomes, from one facet setting.
Negative / Trade-offs
- A dispute is one more aggregate under the card with its own viewer, panel, settings page and door: the largest ADR of the series after the oracle.
- The clocks are the vocabulary’s days, not the schemes’ live rules; a tenant maintains the rows when a scheme changes a window.
- The acquiring mirror is not here; a tenant that acquires sees only the issuer side until that ADR lands.
Neutral
- A
Chargebackclearing line stops being an exception on the batch and becomes a dispute update; ADR-836’s exception code stays for a line naming no dispute the ledger knows.
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.
- Decision 4 — whose lapse. The draft said an overdue representment was the merchant’s win;
it is the cardholder’s, as the example had it. Each contested window now names whose it is,
and a lapse on the bank’s side is the merchant’s win. The step marks
Overdueand never closes; only the processor’s word closes a dispute, so a late update has nothing to race. - Decision 5 —
OnOutcomeposts nothing. The draft posted a credit atWonbeside the reversal, crediting the customer twice. The won reversal is the credit;Neverwas the same thing by another name and is gone. - Decision 6 — “where one was posted.” The clawback and the won-side reversal now say so,
since
OnOutcomeposts no credit. A clawback on a funding account closed since is recorded as forgone and raises a task. - Decision 1 — what may be disputed. Any clearing-line posting, never more than the line less refunds already posted against it, never past the filing limit on the first raise either; a second portion waits for the first to close.
- Decision 3 — withdraw from any open stage; an update behind the current stage or naming
an unknown dispute moves nothing. A
Chargebackclearing line is the scheme’s settlement, recorded on the dispute and posting nothing. - Decision 2 — one window per stage, four of them; the fixture is 30 at every stage.
- Worked example gains the
Arbitrationrow the stages promised.
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
- Overdue representment: D4 said the merchant’s win, the example the cardholder’s.
OnOutcomeatWon: D5 posts a credit, D6 reverses one that was never posted.- One open dispute per transaction vs a partial dispute.
- The clawback assumed a credit exists under
Never. - Bank-side overdue unstated.
- The example skipped
Arbitration. - One window vs per-stage windows.
- The filing limit unstated for the first raise.
- Processor update vs day-end auto-close race.
- Double reversal on a partially refunded purchase.
- Withdrawal after representment.
- A zero-day window.
Phase A (acceptance-test author, 39 questions), 2026-10-02. The rulings that changed a decision:
- Decision 6 — the won purchase is credited back-dated, not reversed. ADR-261’s reversal ignores an amount and undoes every leg, so a partial dispute could never use it; the won outcome posts the dispute credit value-dated as the purchase, and the revaluation cascade re-walks the interest. (The plan grill then removed the reversal altogether; see below.)
- Decision 6 — amount rows re-evaluate, the status row replays. “Every
Setrow replays as recorded” would have kept the statement’s purchases at 12 000 and the scenario false. - Decision 3 — the merchant’s concession is an outcome; the bank’s own concession closes
Lost. The plan had the bank conceding and the cardholder refunded. Pre-arbitration moves to arbitration on the processor’s report, not a second escalation. - Decision 1 — the clearing post keeps an index of its postings. ADR-836’s posting carries no card id, so the raise reads the line from the index the post step writes; refunds that count are scheme reversals by authorisation and earlier won disputes.
- Decision 4 — tasks on the bank’s windows only, one per due date;
Overdueclears when the stage moves. - Decisions 5 and 6 — a dispute posting on an inactive account is forgone and tasked, the provisional credit as much as the clawback; the raise is not refused.
- Decision 8 — the simulator moves at the midpoint of each window, parity in minor units (whole units since the plan grill); a lapse is driven through the stub.
- Decision 7 — the evidence reference is the attachment’s id as a string;
IInboundFileStorewas the wrong store and is gone from the contracts. - Decision 2 — the arbitration window is 45 days in the template; the example follows.
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.
- Decisions 5 and 6 — one credit, value-dated as the purchase; the clawback is a new debit. The plan had a provisional credit today, a won credit back-dated, and ADR-261 reversing the provisional one. The press showed three faults: a credit card’s workflow splits legs on today’s balances, so a back-dated credit on 12 November would have landed unallocated while the re-walk charged catch-up interest and a late fee on a dispute the customer won; ADR-261 reverses at the original’s value date and one leg of several; and nothing could record the reversal’s id. Now the one credit is value-dated as the purchase whenever it posts, posts fixed legs, is final on a win, and a loss re-debits today, as the schemes do.
- Decision 6 — the chargeback line records settlement and never closes. The scheme moves the
money at the first chargeback cycle, a day after the raise; closing
Wonon it would have won every dispute on its second day. The line carries the processor’s dispute reference (CardClearingItemgains it); matching by authorisation settled the wrong partial. - Decision 5 — no
CardPostingKind. Cash advance is decided by merchant category in the type’s YAML (ADR-838); the dispute command carries the merchant fields as the refund command does, and the index stores the clearing kind and the merchant category. - Decision 3 —
ConcedeandMerchantAccepted.Acceptmeant a loss on the verb and a win on the outcome. - Decision 8 — parity in whole currency units; every whole-rand amount is even in cents.
The simulation is its own step behind
RequiresSimulation. - Decision 6 —
onRevaluation: AsRecordedis a generic per-row flag; “a status row” named no subject. ADR-837 is a dependency. - Decision 1 — the dispute id is derived from the purchase and an ordinal, so a concurrent second raise collides on the stream; the posting index has one writer, the post step, and “won so far” is read from the disputes.
- Decision 9 — the money is cascaded from the committed event, existence is checked before
the processor is called, and
cards.disputesis a feature key. - Decision 2 — “category”, the schemes’ word; the filing count named.
- Decision 7 —
AttachmentIdmoves to Contracts rather than freezing a string into an event. - Plan — scenarios added for the bank’s concession and the settlement line; settings reads declared; the task id carries a purpose.
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:
- Decision 6 —
KeepHigher, notAsRecorded, on the grace-status row. PSD2 Article 73 restores the account to the state it would have been in; freezing a lost grace contradicts the standard theOnRaiserule is named for. A re-walk may now restore the interest-free period and never remove it. Bites 1 and 4 re-authored for it. - Decision 9 — the money command checks the account is active before posting and records the fee as posted or forgone too; the dispute’s fee goes to its own funding account.
- Plan — the reason-code validator compared a key to a URN and would have refused the template; it compares the id’s key part now.
- Plan — the five processor calls land in bite 1 on every implementation, the stub included, or bite 1 does not compile; the door’s wire body is the update record itself.
- Plan —
Repeatedis not an outcome: a repeated update returns its stored receipt verbatim. - Plan — read keys are
cards.view-…, the house precedent;CardClearingItem.DisputeReferencedefaults to null so no existing caller breaks. - Plan — a stage reached only through the door may be given by appending the declared events; the fixture’s credit card and current account members are named.
- Stale text struck: Scope’s reversal, Decision 8’s
AcceptDisputeAsync, Decision 7’s string reference, the deadlines step’s feature key, the example’s clawback row.
Notes
- Depends on ADR-835 (Shipped), ADR-836, ADR-837, ADR-838 and ADR-839 (Accepted): the card, the clearing post with its merchant data, the revaluation cascade on a back-dated external posting (ADR-837 bite 5), the deferred-interest rows and the card fee. Every bite but 1 starts after ADR-836 lands; bite 4 after ADR-838 and ADR-839 too.
- Standards: PSD2 (EU 2015/2366) Article 73 — refund of an unauthorised transaction by the
end of the next business day — is the
OnRaiserule on fraud and unauthorised-use codes; a register row,Partial, for an EU tenant. The schemes’ dispute rules (Visa Core Rules, the Mastercard Chargeback Guide) give the stages and the windows; a register row names them as the source of the vocabulary’s starter set, not as a claim of currency. - The acquiring side, the price card and merchant settlement follow in the series.
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).