This is the build plan for this decision record, bite by bite, as it was grilled and built. 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-843 — Implementation Plan
Findings for the ADR
- F1 — the reserve is ADR-836’s second reductions holder (D1). Accounts changes by one figure
only:
AccountAvailabilitygainsUnclearedFunds, the uncleared-funds claims held, so the free balance can add the T+n holds back (D4).ClaimId, the claim enums and the account’s claim verbs stay where they are. - F2 — every bite depends on ADR-842, which depends on ADR-836 and ADR-841 batch A; bite 1
also needs ADR-840’s reason-code settings and
AttachmentIdin Contracts. Nothing starts onmain. - F3 — ADR-842’s contract records gain members here:
MerchantAgreementTerms(Reserve,StepUp, both trailing and optional),AcquiringFeedLine(ReasonCode,OriginalProcessorReference,ChargebackOutcome, trailing and optional),AcquiringFeedLineKind.ChargebackFinal,AcquiringSettings(WarnDaysBeforeDeadline,DisputesGroup). A landing note on ADR-842 keeps the two lanes from fighting over them. - F4 — the tasks command follows ADR-840’s, keyed
tasks.request-merchant-chargeback-follow-up-task, withTaskSubjectTypes.MerchantChargeback; its task id derives from the case and the due date. - F5 — the step commands take their derived keys (
acquiring.release-merchant-reserve,acquiring.reserve-merchant-settlement,acquiring.post-merchant-chargeback-line,acquiring.watch-merchant-chargeback-deadlines,acquiring.monitor-merchant-disputes), as ADR-840’s deadline command does. - F6 — pre-existing, F-1801: the account detail never applies
ClaimMarkedUnbacked. - F7 — wind-down is never gated (ADR-363 D3; F-1803). The release step and the deadline step carry no feature key. ADR-842’s payout step has the same flaw; a landing note there corrects it.
- F8 — a tuple list is not stored (F-1804). Marten’s serialiser drops tuple fields, so every list on a
document here is a named record. ADR-842’s
MerchantIdentifierHistory.Holdershas the same flaw; a landing note there corrects it. - F9 — eight projects, one ADR. The domain change is in Acquiring; the rest is a field on availability, two Accounts handlers, a Cards reader and a Tasks command — each a seam, none a second body of work.
Files touched
Bite 1 — the contracts, the reserve days and their reduction
src/LedgerTM.Contracts/Acquiring/MerchantReserve.cs— new;MerchantReserveDayId,ReserveKind,ReserveRule,ReserveTarget,StepUpRulesrc/LedgerTM.Contracts/Acquiring/MerchantChargeback.cs— new;MerchantChargebackId,MerchantChargebackStage,MerchantChargebackOutcomesrc/LedgerTM.Contracts/Acquiring/MerchantAgreement.cs,AcquiringFeed.cs(ADR-842’s) — the terms’ rules, the line’s three members,ChargebackFinalsrc/LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs— the two chargeback commands;TransactionSource,ExternalIntegrations(and converter, validator) — the two sourcessrc/LedgerTM.Contracts/Accounts/IAccountAvailabilityReader.cs(ADR-836’s) —AccountAvailability.UnclearedFunds;src/LedgerTM.Accounts/Application/Queries/AccountAvailabilityReader.cs— fills itsrc/LedgerTM.Contracts/Cards/ICardDisputeReasonCodeReader.cs— new;src/LedgerTM.Cards/Application/Settings/CardDisputeReasonCodeReader.cs— newsrc/LedgerTM.Contracts/Tasks/RequestMerchantChargebackFollowUpTaskCommand.cs— newsrc/LedgerTM.Acquiring/Application/Reserve/MerchantReserveDay.cs,MerchantReserveDayProjection.cs,AcquiringReductionsReader.cs— new; the inline documents (MerchantReserveDay,MerchantReserveBalance) and Acquiring’sIAvailableBalanceReductionsReader;Bootstrapper.cs— registers it beside Cards’src/LedgerTM.Acquiring/Domain/MerchantAgreement.cs,.Events.cs(ADR-842’s) — the reserve events; the terms’ rules validated (MERCHANT_RESERVE_NEEDS_DELAY,MERCHANT_RESERVE_RULE_INVALID)src/LedgerTM.Acquiring/Application/Agreements/AcquiringSettings.cs(ADR-842’s) —WarnDaysBeforeDeadline,DisputesGroupsrc/LedgerTM.Infrastructure.Contracts/AccessControl/PermissionCatalog.cs— every keysrc/LedgerTM.Hosting/event-identity.tsv— the fifteen new events;LedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsv— the new documents and the changed recordsLedgerTM.Tests.Component/Acquiring/MerchantReserveReductionTests.cs— new
Bite 2 — the reserve
src/LedgerTM.Acquiring/Application/Reserve/ReleaseMerchantReserveStep.cs— new; step 49, no feature key,ReleaseMerchantReserveCommandsrc/LedgerTM.Acquiring/Application/Reserve/ReserveMerchantSettlementStep.cs— new; step 50,ReserveMerchantSettlementCommand, rolling and fixed, the running cap, settled dates and the shortfall;[ReplaySafe]on both steps’ handlerssrc/LedgerTM.Acquiring/Application/DayEnd/MerchantPayoutStep.cs(ADR-842’s) — skip an account with a released date not yet reservedsrc/LedgerTM.Acquiring/Application/DayEnd/AcquiringFeedCommands.cs(ADR-842’s) — record each date’s gross (MerchantSalesPostedForDate)src/LedgerTM.Acquiring/Application/Reserve/GetMerchantReserve.cs— newLedgerTM.Tests.Component/Acquiring/MerchantReserveTests.cs— new
Bite 3 — chargebacks
src/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.cs— the two handlerssrc/LedgerTM.Acquiring/Domain/MerchantChargeback.cs,.Events.cs— newsrc/LedgerTM.Acquiring/Application/DayEnd/AcquiringFeedCommands.cs(ADR-842’s post step) —PostMerchantChargebackLineCommand, one unit of work per line; checks before the post; consumption oldest first, keyed by line and day; a closed agreement’s chargeback raises a taskdocs/adr/ADR-842-tests/bite-2.cs.txt(as copied into the test project) — the chargeback and reversal lines no longer readCHARGEBACK_NOT_HANDLED; re-dispatch ADR-842’s bite-2 author for that testsrc/LedgerTM.Tasks/Application/Commands/RequestMerchantChargebackFollowUpTask.cs— new;src/LedgerTM.Tasks/Domain/TaskSubjectTypes.cs—MerchantChargeback(moved from bite 4: bite 3’s closed-agreement chargeback raises the task)src/LedgerTM.Acquiring/Application/Chargebacks/MerchantChargebackSummaryProjection.cs,GetMerchantChargeback.cs,ListMerchantChargebacks.cs— newsrc/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/AccountTypesSettings.yaml— the three types and two workflows;countries/za/retail-bank/PriceSettings.yaml—chargeback-fee(selectorstage);PostingSettings.yaml— the legsLedgerTM.Tests.Component/Acquiring/MerchantChargebackTests.cs— new
Bite 4 — representment and clocks
src/LedgerTM.Acquiring/Application/Chargebacks/RecordMerchantRepresentment.cs,AcceptMerchantChargeback.cs,MerchantChargebackApproverViewReader.cs— new;MerchantChargebackIsItsOwnHoldersrc/LedgerTM.Acquiring/Application/DayEnd/MerchantChargebackDeadlinesStep.cs— new; step 56, no feature keyLedgerTM.Tests.Component/Acquiring/MerchantChargebackDeadlinesTests.cs— new
Bite 5 — monitoring
src/LedgerTM.Acquiring/Application/DayEnd/MonitorMerchantDisputesStep.cs— new; step 57src/LedgerTM.Acquiring/Domain/MerchantAgreement.cs—RecordDisputeRatios,StepUpReserve;Application/Agreements/GetMerchantAgreement.cs—DisputeRatios,StepUpsLedgerTM.Tests.Component/Acquiring/MerchantDisputeMonitoringTests.cs— new
Bite 6 — the screens, the sample, the probe, the guide
src/ui-apps/bank/src/features/acquiring/merchant-reserve-panel.tsx,merchant-chargebacks-panel.tsx,merchant-chargeback-viewer.tsx,merchant-chargeback-dialogs.tsx— new;merchant-agreement-viewer.tsxgains the panels;app.tsx(routemerchant-chargebacks/{id});hooks/acquiring.tssrc/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedSampleMerchant.cs(ADR-842’s) — the reserve rule and a sample chargebacksrc/ui-apps/bank/ui-review/adr-uat/flows/adr-843-server-probe.ts— newdocs/guide/features/merchant-reserve.md,merchant-chargebacks.md— newLedgerTM.Tests.Component/Acquiring/MerchantChargebackViewerTests.cs— new
Prior art
The plan grill added supporting types that carry no decision beyond the ADR’s:
MerchantReserveBalance, ReserveConsumption, MerchantReserveOutstanding, ChargebackMoney,
MerchantDisputeRatioView, MerchantReserveStepUpView. CardDisputeReasonCodeView takes
ADR-840’s word for the vocabulary.
Interfaces
// LedgerTM.Contracts/Acquiring/MerchantReserve.cs — new (D1, D2, D6)
public readonly record struct MerchantReserveDayId(string Value) : IStrongId<MerchantReserveDayId> { … } // For(AccountId account, DateOnly businessDate, int n): "{account}-reserve-{yyyyMMdd}-{n}", n from the agreement, starting at 1
public enum ReserveKind { Rolling, Fixed }
public sealed record ReserveTarget(CurrencyId Currency, decimal Amount);
public sealed record ReserveRule(ReserveKind Kind, decimal Rate /* a fraction, 0 < Rate <= 0.5 */, int? HoldCalendarDays /* Rolling, 1..720 */, IReadOnlyList<ReserveTarget>? Targets /* Fixed: one per settlement currency */, int? ReleaseCalendarDaysAfterTermination /* Fixed, 0..720 */);
public sealed record StepUpRule(decimal RatioThreshold /* a fraction */, int CountThreshold, ReserveRule SteppedRule);
// MerchantAgreementTerms (ADR-842) gains two trailing optional members: ReserveRule? Reserve = null (null: no reserve), StepUpRule? StepUp = null.
// MERCHANT_RESERVE_RULE_INVALID also covers: a Rolling rule carrying Targets or ReleaseCalendarDaysAfterTermination; a Fixed rule carrying HoldCalendarDays or no release period; a target Amount <= 0; two targets in one currency; a target in a currency the agreement does not settle in;
// StepUp RatioThreshold outside (0, 1] or CountThreshold < 1. MERCHANT_RESERVE_NEEDS_DELAY is reported first. Adding a settlement currency checks every terms row in force on or after its date.
// Refusals, at open and at every terms amendment, the stepped rule validated exactly as Reserve is: MERCHANT_RESERVE_NEEDS_DELAY (Reserve or StepUp with SettlementDelayBusinessDays 0),
// MERCHANT_RESERVE_RULE_INVALID (a value out of range; a fixed rule missing a settlement currency's target; a settlement currency added to a fixed rule without its target).
// LedgerTM.Contracts/Acquiring/MerchantChargeback.cs — new (D3)
public readonly record struct MerchantChargebackId(string Value) : IStrongId<MerchantChargebackId> { … } // For(InstitutionConnectionId connection, string scheme /* lower-cased */, string schemeCaseReference)
public enum MerchantChargebackStage { Received, Represented, Reversed, PreArbitration, Closed }
public enum MerchantChargebackOutcome { Won, Lost } // the merchant's view: Won means the merchant keeps the money
// LedgerTM.Contracts/Acquiring/AcquiringFeed.cs — changed (D3): AcquiringFeedLineKind gains ChargebackFinal; AcquiringFeedLine gains three trailing optional members:
// string? ReasonCode = null (as the scheme writes it), string? OriginalProcessorReference = null, MerchantChargebackOutcome? ChargebackOutcome = null (on a final line).
// A chargeback-family line's TransactionDate is the original sale's date; that is what routes it to an agreement.
// AcquiringFeedOutcomes gains CaseReferenceMissing (terminal), CaseUnknown (non-terminal), ReversalExceedsChargeback (non-terminal), ChargebackAgreementClosed (terminal), and the notes CaseReopened and ReasonCodeUnknown. A final line records Posted with no transaction.
// LedgerTM.Contracts/Accounts/IAccountAvailabilityReader.cs — changed (D4): AccountAvailability gains a trailing decimal UnclearedFunds — the Reduce claims of origin UnclearedFunds
// on the standard positions Available sums. ADR-837 adds FacilityAvailable the same way: whichever lands second appends after the other.
// LedgerTM.Contracts/Cards/ICardDisputeReasonCodeReader.cs — new (D3)
public sealed record CardDisputeReasonCodeView(CardDisputeReasonCodeId Id, string Scheme, string Code, string Label, int RepresentmentDays, int ResponseDays, int PreArbitrationDays, int ArbitrationDays);
public interface ICardDisputeReasonCodeReader { Task<CardDisputeReasonCodeView?> FindAsync(string scheme, string code, CancellationToken ct = default); Task<CardDisputeReasonCodeView?> GetAsync(CardDisputeReasonCodeId id, CancellationToken ct = default); } // Cards implements over ADR-840's settings; the scheme matched case-insensitively; null → REASON_CODE_UNKNOWN, thirty-day windows
// LedgerTM.Acquiring/Application/Reserve/MerchantReserveDay.cs — new (D1, D2); inline documents, one writer (the agreement's events)
public sealed record ReserveConsumption(MerchantChargebackId Chargeback, MerchantReserveDayId Day, TransactionId Line, decimal Amount, DateOnly On);
// Documents and summaries carry public get/set properties and load by their strong id. Namespaces: events and value records in LedgerTM.Acquiring.Domain; reads beside their files (Application.Reserve, Application.Chargebacks, Application.Agreements); step commands beside their steps.
public sealed class MerchantReserveDay { MerchantReserveDayId Id; MerchantAgreementId Agreement; AccountId Account; CurrencyId Currency; DateOnly BusinessDate; ReserveKind Kind; decimal Withheld; DateOnly WithheldOn;
DateOnly? ReleaseOn /* Rolling */; int? ReleaseCalendarDaysAfterTermination /* Fixed, carried from the rule that withheld it */; DateOnly? ReleasedOn; List<ReserveConsumption> Consumptions;
decimal Consumed => Consumptions.Sum(c => c.Amount); decimal Outstanding => ReleasedOn is null ? Withheld - Consumed : 0; }
public sealed class MerchantReserveBalance { AccountId Id; decimal Outstanding; } // one per settlement account, kept by the same inline projection
public sealed class AcquiringReductionsReader : IAvailableBalanceReductionsReader // an account id without ForMerchantSettlement's prefix → zero, no session opened; otherwise one load of MerchantReserveBalance by id
// Agreement events (D1, D2, D4, D6), [MessageIdentity("acquiring.merchant-…")]:
// MerchantSalesPostedForDate(Id, Account, BusinessDate, Gross, ReleaseOn) — one per (account, business date) per post run; ReleaseOn is the hold's release date as raised; appended in the session that records the batch's line outcomes, so a redelivered post adds nothing;
// MerchantReserveWithheld(Id, Day, Account, BusinessDate, Amount, Kind, ReleaseOn?, ReleaseCalendarDaysAfterTermination?, On); MerchantReserveDateSettled(Id, Account, BusinessDate, MerchantReserveSettledReason Reason, On) — enum MerchantReserveSettledReason { Required, TargetReached, Terminated };
// MerchantReserveShortfallRecorded(Id, Account, BusinessDate, Unreserved, On) — once per date, when the shortfall arises; MerchantReserveConsumed(Id, Day, Chargeback, Line /* TransactionId */, Amount, On) — once per (Line, Day);
// MerchantReserveReleased(Id, Day, On); MerchantDisputeRatioRecorded(Id, Month /* DateOnly, the first of the month */, IReadOnlyList<MerchantSchemeRatio> Ratios) — MerchantSchemeRatio(string Scheme, int Sales, int Chargebacks, decimal? Ratio /* null: chargebacks and no sales, over any threshold; else half-up to six places */);
// MerchantReserveSteppedUp(Id, ReserveRule SteppedRule, DateOnly EffectiveFrom, DateOnly Month, string Scheme, int Sales, int Chargebacks).
// LedgerTM.Acquiring/Application/Reserve/ReleaseMerchantReserveStep.cs — new (D2); wind-down, so no feature key (ADR-363 D3); a date's money is released in the day-end that closes it
public sealed class ReleaseMerchantReserveStep(IMessageBus bus) : IDayEndStep // "acquiring.release-merchant-reserve", 49, PreIncrement, NonCritical, FeatureKey null
[PermissionKey("acquiring.release-merchant-reserve")] public record ReleaseMerchantReserveCommand(TenantId Tenant, MerchantAgreementId Agreement, DateOnly TradingDate) : ICommand, ISystemCommand;
// Per agreement with an outstanding reserve day: Rolling ReleaseOn <= date; Fixed date >= TerminatedOn + the day's own ReleaseCalendarDaysAfterTermination → MerchantReserveReleased.
// LedgerTM.Acquiring/Application/Reserve/ReserveMerchantSettlementStep.cs — new (D2)
public sealed class ReserveMerchantSettlementStep(IMessageBus bus) : IDayEndStep // "acquiring.reserve-merchant-settlement", 50, PreIncrement, NonCritical, FeatureKey null (wind-down: it reserves only sales already posted; ruled at phase B)
[PermissionKey("acquiring.reserve-merchant-settlement")] public record ReserveMerchantSettlementCommand(TenantId Tenant, MerchantAgreementId Agreement, DateOnly TradingDate) : ICommand, ISystemCommand; // per agreement via InvokeForTenantAsync
// Per settlement account: read availability once; cap = max(0, Available), a running figure each withholding lowers. For each business date d, ascending, with ReleaseOn(d) <= date, not settled, under TermsOn(d).Reserve:
// Gross(d) = the date's Sale lines' settlement amounts (refunds do not lower it); Required(d) = round-half-up(Rate × Gross(d)); want = Required(d) − Withheld(d); Fixed: want = min(want, target − fixed outstanding in the currency); a fixed date after termination settles (Terminated);
// amount = min(want, cap); amount > 0 → MerchantReserveWithheld (n = the date's next increment; Rolling ReleaseOn = date + HoldCalendarDays, Fixed carries the rule's ReleaseCalendarDaysAfterTermination);
// Withheld(d) == Required(d) → settled (Required); a fixed date capped by its target → settled (TargetReached); else want > cap → MerchantReserveShortfallRecorded once, and the date waits for a later run.
// Under a fixed rule a consumption reopens withholding only for dates released after it.
// MerchantPayoutStep (ADR-842) skips an account with any released date not settled while a rule governed it.
[PermissionKey("acquiring.view-merchant-reserve")] public record GetMerchantReserveQuery(MerchantAgreementId Id) : IQuery<MerchantReserveView>;
public sealed record MerchantReserveOutstanding(CurrencyId Currency, decimal Amount);
public sealed record MerchantReserveShortfallView(CurrencyId Currency, DateOnly BusinessDate, decimal Unreserved); // live: Required − Withheld on each released, unsettled date
public sealed record MerchantReserveView(IReadOnlyList<MerchantReserveDayView> Days, IReadOnlyList<MerchantReserveOutstanding> Outstanding, IReadOnlyList<MerchantReserveShortfallView> Shortfalls); // an unknown agreement → 404
public sealed record MerchantReserveDayView(MerchantReserveDayId Id, CurrencyId Currency, DateOnly BusinessDate /* the batch's */, DateOnly WithheldOn, ReserveKind Kind, decimal Withheld, decimal Consumed, decimal Released /* Withheld − Consumed at release */, decimal Outstanding,
DateOnly? ReleaseOn /* Rolling; Fixed once the agreement has terminated */, int? ReleaseCalendarDaysAfterTermination, DateOnly? ReleasedOn, IReadOnlyList<ReserveConsumption> Consumptions);
// LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs — new (D3, D4)
[PermissionKey("accounts.process-merchant-chargeback")] public record ProcessMerchantChargebackCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount /* settlement */, DateOnly TradingDate /* run date */, DateOnly ValueDate /* the batch's business date */, string SourceRef /* the case id */, IReadOnlyDictionary<string, string>? PricingAttributes = null) : ISystemCommand; // stage: first | pre-arbitration
[PermissionKey("accounts.process-merchant-chargeback-reversal")] public record ProcessMerchantChargebackReversalCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount /* settlement */, DateOnly TradingDate, DateOnly ValueDate, string SourceRef) : ISystemCommand;
// workflows: merchant-chargeback → MerchantChargeback $amount; ChargebackFeeCharged fee('chargeback-fee', valueDate, $amount) under > 0, a taxable fee row whose VAT slice posts with it;
// merchant-chargeback-reversal → MerchantChargebackReversed $amount. No guard: the scheme's fact.
// LedgerTM.Acquiring/Domain/MerchantChargeback.cs — new (D3, D4, D5)
public sealed class MerchantChargeback : EventSourcedAggregate
{
public void EnsureCanRecord(AcquiringFeedLineKind kind, TransactionId line, decimal transactionAmount); // emits nothing; refuses REVERSAL_EXCEEDS_CHARGEBACK (transaction-currency amounts) and MERCHANT_CHARGEBACK_STAGE_FORBIDS before any post
public void Receive(MerchantAgreementId agreement, AccountId account, string scheme, string schemeCaseReference, string? saleReference, decimal amount, CurrencyId currency, CardDisputeReasonCodeId? reasonCode, DateOnly dueOn, DateOnly on); // nothing on a case already received
public void RecordMoney(AcquiringFeedLineKind kind, TransactionId line, decimal transactionAmount, decimal settlementAmount, DateOnly? dueOn, DateOnly on); // nothing for a line already recorded; a Chargeback line is first when no other Chargeback line is recorded, later → PreArbitration; a Reversal → Reversed; on a Closed case → reopens (CASE_REOPENED), a Chargeback line at PreArbitration with no fee
public void RecordReserveConsumed(MerchantReserveDayId day, TransactionId line, decimal amount, DateOnly on);
public void Represent(AttachmentId? evidence, string description, DateOnly submittedOn, DateOnly expectedBy, UserId by); // Received or PreArbitration → Represented; submittedOn in [receivedOn /* the opening line's business date */, today] else MERCHANT_REPRESENTMENT_DATE_INVALID; a Closed case → MERCHANT_CHARGEBACK_CLOSED
public void MarkOverdue(DateOnly on); // the acquirer's own windows only; Overdue clears when the case moves to its next stage
public void Close(MerchantChargebackOutcome outcome, string? updateReference, string? reason, UserId? by, DateOnly on); // a ChargebackFinal line, or the bank's accept (Lost, its reason recorded, the maker as By) from Received, Represented or PreArbitration
// Refusals: MERCHANT_CHARGEBACK_CLOSED, MERCHANT_CHARGEBACK_STAGE_FORBIDS (represent needs Received or PreArbitration; accept refused on Reversed)
}
// Events ([MessageIdentity("acquiring.merchant-chargeback-…")]): MerchantChargebackReceived(Id, Agreement, Account, Scheme, SchemeCaseReference, SaleReference?, Amount, Currency, ReasonCode? /* CardDisputeReasonCodeId */, DueOn, On),
// MerchantChargebackMoneyRecorded(Id, Stage, Line /* TransactionId */, TransactionAmount, SettlementAmount, DueOn?, On), MerchantChargebackReserveConsumed(Id, Day, Line, Amount, On), MerchantChargebackRepresented(Id, Evidence?, Description, SubmittedOn, ExpectedBy, By),
// MerchantChargebackOverdue(Id, Stage, On), MerchantChargebackClosed(Id, Outcome, UpdateReference?, Reason?, By?, On), MerchantChargebackReopened(Id, Stage, On).
// LedgerTM.Acquiring/Application/DayEnd/AcquiringFeedCommands.cs — the post step (ADR-842's), changed in bite 3
[PermissionKey("acquiring.post-merchant-chargeback-line")] public record PostMerchantChargebackLineCommand(TenantId Tenant, AcquiringFeedBatchId Batch, string ProcessorReference, DateOnly TradingDate) : ICommand, ISystemCommand;
// The batch handler posts its Sale and Refund lines first, then invokes this per chargeback-family line, in file order, one at a time through InvokeForTenantAsync; each line is its own unit of work and records its own outcome; [ReplaySafe].
// Per line: no SchemeCaseReference → CASE_REFERENCE_MISSING; a Reversal or Final on no case → CASE_UNKNOWN (re-scanned); routed to a closed agreement → the case opens with no money, CHARGEBACK_AGREEMENT_CLOSED (terminal), and a follow-up task;
// else case.EnsureCanRecord (the reversal cap cumulative against every Chargeback line's transaction amount, pre-arbitration included) → the Accounts command (dedup by the line's TransactionId, settlement amount) → Receive and RecordMoney; then, after a Chargeback posts, free = Available + UnclearedFunds read fresh as of the run date;
// free < 0 → consume the account's reserve days by business date ascending until covered, MerchantReserveConsumed once per (Line, Day) on the agreement and RecordReserveConsumed on the case; ChargebackFinal → Close(ChargebackOutcome), no money.
// ADR-842's CHARGEBACK_NOT_HANDLED lines are non-terminal and re-scanned into this path.
// LedgerTM.Acquiring/Application/Chargebacks/… — new (D5, D7)
[PermissionKey("acquiring.record-merchant-representment")] public record RecordMerchantRepresentmentCommand(MerchantChargebackId Id, AttachmentId? Evidence, string Description, DateOnly SubmittedOn) : ICommand, INotFourEyesGated { Target "MerchantChargeback" } // reason: it records a submission already made in the processor's portal; expectedBy = SubmittedOn + ResponseDays
[PermissionKey("acquiring.accept-merchant-chargeback")] public record AcceptMerchantChargebackCommand(MerchantChargebackId Id, string Reason) : ICommand { Target "MerchantChargeback" } // its validator refuses a Reversed or Closed case before capture
// The bus queries are ungated; the HTTP routes carry FeatureRoute "cards.acquiring". The list and reserve reads answer 404 for an unknown agreement.
public sealed class MerchantChargebackApproverViewReader() : DocumentApproverViewReader<MerchantChargebackSummary, MerchantChargebackId>("MerchantChargeback"); public sealed class MerchantChargebackIsItsOwnHolder() : SelfHoldingAggregate("MerchantChargeback");
public sealed record ChargebackMoney(MerchantChargebackStage Stage, TransactionId Line, decimal TransactionAmount, decimal SettlementAmount, DateOnly On);
public sealed record MerchantChargebackEvidence(AttachmentId? Attachment, string Description, DateOnly SubmittedOn);
public sealed class MerchantChargebackSummary { MerchantChargebackId Id; MerchantAgreementId Agreement; AccountId Account; string Scheme; string SchemeCaseReference; string? SaleReference; decimal Amount; CurrencyId Currency; string? SchemeReasonCode /* raw */; CardDisputeReasonCodeId? ReasonCode; string? ReasonLabel;
MerchantChargebackStage Stage; MerchantChargebackOutcome? Outcome; DateOnly ReceivedOn; DateOnly? DueOn /* the acquirer's; null while the scheme's move */; DateOnly? ExpectedBy /* the scheme's; a Reversed case never represented: reversal + ResponseDays */; bool Overdue; bool AwaitingScheme /* read time */;
IReadOnlyList<ChargebackMoney> Money /* the scheme's amounts; the fee is on the account */; IReadOnlyList<ReserveConsumption> ReserveConsumed; MerchantChargebackEvidence? Evidence; string? ClosedReason; DateOnly OpenedOn; DateOnly? ClosedOn; }
[PermissionKey("acquiring.view-merchant-chargeback")] public record GetMerchantChargebackQuery(MerchantChargebackId Id) : IQuery<MerchantChargebackSummary?>;
[PermissionKey("acquiring.list-merchant-chargebacks")] public record ListMerchantChargebacksQuery(MerchantAgreementId Agreement) : IQuery<IReadOnlyList<MerchantChargebackSummary>>;
// Routes: POST /api/merchant-chargebacks/{id}/{represent|accept}, GET /api/merchant-chargebacks/{id}, GET /api/merchant-agreements/{id}/chargebacks, GET /api/merchant-agreements/{id}/reserve.
public sealed class MerchantChargebackDeadlinesStep(IMessageBus bus) : IDayEndStep // "acquiring.merchant-chargeback-deadlines", 56, PostIncrement, NonCritical, FeatureKey null (wind-down); the step passes ctx.TradingDate + 1, the trading day being opened
[PermissionKey("acquiring.watch-merchant-chargeback-deadlines")] public record WatchMerchantChargebackDeadlinesCommand(DateOnly TradingDate) : ICommand, ISystemCommand { Target "MerchantChargebackDeadlines" }
// Received or PreArbitration with DueOn − WarnDays <= date → RequestMerchantChargebackFollowUpTaskCommand (task id from the case and DueOn); DueOn < date and not Overdue → MarkOverdue. Represented/Reversed past ExpectedBy → AwaitingScheme (summary only).
[PermissionKey("tasks.request-merchant-chargeback-follow-up-task")] public record RequestMerchantChargebackFollowUpTaskCommand(MerchantChargebackId ChargebackId, string Title, string Description, UserGroupId? OfferedToGroupId, DateOnly DueOn) : ISystemCommand;
// AcquiringSettings (ADR-842, ClosureTailDays) gains: public int WarnDaysBeforeDeadline { get; set; } = 5; public UserGroupId? DisputesGroup { get; set; }
// LedgerTM.Acquiring/Application/DayEnd/MonitorMerchantDisputesStep.cs — new (D6)
public sealed class MonitorMerchantDisputesStep(IMessageBus bus) : IDayEndStep // "acquiring.monitor-merchant-disputes", 57, PostIncrement, NonCritical, "cards.acquiring"; acts for every completed month not yet recorded
[PermissionKey("acquiring.monitor-merchant-disputes")] public record MonitorMerchantDisputesCommand(TenantId Tenant, MerchantAgreementId Agreement, DateOnly TradingDate) : ICommand, ISystemCommand; // per Active or Suspended agreement via InvokeForTenantAsync; the step passes ctx.TradingDate + 1
// Per agreement, per scheme (lower-cased): sales = Sale lines posted with business dates in the month; chargebacks = cases opened by batches whose business dates fall in it, a case counted once; a month recorded once, a later batch for it not re-counted; ratio = sales == 0 ? (chargebacks > 0 ? null : 0) : chargebacks / sales;
// StepUp present and any scheme with (ratio null or ratio >= RatioThreshold) and chargebacks >= CountThreshold, and the rule in force not as strict (as strict = same kind, Rate >=, Rolling HoldCalendarDays >=, Fixed every target >= and release >=) → StepUpReserve, the system's own verb (never the clerk's amend, so no four-eyes capture): MerchantReserveSteppedUp and a dated terms row from the step's date, keeping StepUp.
// MerchantAgreementSummary (ADR-842) gains IReadOnlyList<MerchantDisputeRatioView(DateOnly Month, string Scheme, int Sales, int Chargebacks, decimal? Ratio)> DisputeRatios and IReadOnlyList<MerchantReserveStepUpView(DateOnly EffectiveFrom, string Scheme, int Sales, int Chargebacks)> StepUps.
// Configuration — AccountTypesSettings.yaml, MerchantSettlementAccount: MerchantChargeback (Dr Current), MerchantChargebackReversed (Cr Current), ChargebackFeeCharged (Dr Current, taxable); externalIntegrations merchantChargeback, merchantChargebackReversal
// countries/za/retail-bank/PriceSettings.yaml: chargeback-fee (Amount, selectors [stage: first|pre-arbitration]) {} 0, { stage: first } 150.00 on the rand list (15.00 on the euro list), net of VAT
// PostingSettings.yaml: MerchantChargeback Dr Merchant payable / Cr Scheme settlement receivable; MerchantChargebackReversed the reverse; ChargebackFeeCharged Dr Merchant payable / Cr Acquiring fee income
As shipped (reconciled at land, ADR-692 D21). Differences from the signatures above:
MerchantSettlementAccounts.IsOne/CurrencyOf(AccountId)(Acquiring.Domain) reads a settlement account’s derived id;FreeBalance.Of(AccountAvailability)=Ledger - (Claims - UnclearedFunds) - ExternalReductions.MerchantReserveBalancealso carriesList<MerchantReserveDayOutstanding> Days; both reserve documents areMultiStreamProjections.MerchantReserveConsumed,MerchantReserveReleasedand the reserve state live onMerchantAgreement(ReserveDates,ReserveDays,ReserveConsumptions,RecordedDisputeMonths); verbsRecordSalesPosted,ReserveSettlement(account, available, date),ReleaseReserve(date),ConsumeReserve(account, chargeback, line, shortfall, on),MonitorDisputes(months, date).ListReservingMerchantAgreementsQuery(acquiring.list-reserving-merchant-agreements) feeds the reserve and monitoring steps.MerchantChargebackReceivedgains trailingSchemeReasonCode,ReasonLabel;MerchantChargebackMoneyRecordedgains trailingExpectedBy.MerchantChargeback.RecordMoney(kind, line, transactionAmount, settlementAmount, MerchantChargebackWindows windows, on)returns whether it reopened;Represent(evidence, description, submittedOn, windows, by, today);MarkOverdue(dueOn, on);Accept(reason, by, on); the aggregate’s money list isMerchantChargebackLine, the read’s isChargebackMoney.AcquiringFeedOutcomes.CaseReopenedand.ReasonCodeUnknownare notes held on the outcomes class;AcquiringFeedPost.IsChargebackFamily(line).PostMerchantChargebackLineCommand’s handler returns the line’sAcquiringFeedLineOutcome?;AcquiringRoutes.RequireOnAsyncgates the three HTTP reads.
Bites
| Bite | Description | Acceptance criterion | Status |
|---|---|---|---|
| 1 | The contracts: the reserve rule and days, the chargeback ids and stages, the line’s members, the reason-code reader, the task command, the chargeback commands; the reserve-day documents and Acquiring’s reductions reader; the availability reader’s uncleared funds | a reserve day reduces the settlement account’s available balance wherever it is read | Done |
| 2 | The reserve: the release step at 49 and the withholding step at 50, rolling and fixed, the cap and the shortfall, the payout’s skip, the reserve read | a rolling reserve withholds a day’s percentage as its holds release and returns it on its date; a fixed reserve builds to its target and is held until after termination | Done |
| 3 | Chargebacks: one unit of work per line, the aggregate opened by the feed, the debit and fee, the reserve consumed oldest-first, the reversal, pre-arbitration and the final | a chargeback debits the merchant and its fee, and the reserve bears what the free balance cannot, oldest first; a reversal returns the amount and keeps the fee | Done |
| 4 | Representment and clocks: record, accept, the deadlines step, the task | a representment is recorded and the clock is watched; a clerk accepts a case for the merchant | Done |
| 5 | Monitoring: the monthly ratio, the step-up | a merchant over both thresholds has its reserve stepped up from the first of the month | Done |
| 6 | The Reserve and Chargebacks panels, the case viewer, the sample, the probe, the guide, the register | an operator follows a chargeback from the feed to the reserve it consumed | Done |
Scenarios
Feature: an acquirer holds back part of what it owes, and the merchant's side of a dispute runs in the ledger
# Bite 1
Scenario: a reserve day reduces the settlement account's available balance wherever it is read
Given a merchant's settlement account with 100.00 available and a card hold of 10.00 on another account
When the agreement withholds a reserve day of 40.00, then a chargeback consumes 15.00 of it, then the day is released
Then the account's available balance reads 60.00, 75.00 and 100.00 through the availability read, the account detail and the payout's guard
And the card hold still reduces only its own account, and an account that is not a merchant settlement account reads no reserve
# Seen at: route:/accounts/{id}
# Bite 2
Scenario: a rolling reserve withholds a day's percentage as its holds release and returns it on its date
Given the worked example's agreement with a 5% rolling reserve for 180 days
When a 1 000.00 sale's hold releases on Wednesday
Then a reserve of 50.00 is withheld that day, the payout the next day is 941.34, and the 50.00 becomes available again on 5 April
And running the reserve step twice for one date withholds once, a day of 1 000.01 withholds 50.00 and holds no payout back for the cent, a day whose available balance is only 20.00 withholds 20.00 and the rest the next day it is free, a payout waits for a released date not yet reserved, and a reserve rule on a T+0 agreement is refused
# Seen at: route:/merchant-agreements/{id}
# Bite 2
Scenario: a fixed reserve builds to its target and is held until after termination
Given an agreement with a 10% fixed reserve to a target of 150.00, released 90 days after termination
When three days of 1 000.00 sales release
Then 100.00 and then 50.00 are withheld and nothing on the third day, and each day's payout pays the rest
And the 150.00 is released 90 days after the agreement terminates, even with acquiring switched off, and amending the release period later does not move it
# Seen at: route:/merchant-agreements/{id}
# Bite 3
Scenario: a chargeback debits the merchant and its fee, and the reserve bears what the free balance cannot, oldest first
Given the worked example's account with 50.00 held as reserve and nothing free
When a chargeback of 30.00 arrives in the feed
Then the account is debited 30.00, the chargeback fee of 150.00 and its VAT of 22.50, the reserve day is consumed by 50.00, and the merchant owes 152.50
And with two reserve days held the older is consumed first, two chargebacks on one account in one feed consume no more than the shortfall between them, a chargeback the sales still on hold can bear consumes no reserve, and a redelivered post consumes nothing twice
# Seen at: route:/merchant-chargebacks/{id}
# Bite 3
Scenario: a reversal returns the amount and keeps the fee
Given the case from the chargeback
When the feed carries its reversal
Then the account is credited 30.00, the case reads reversed, and the fee stands
And a reversal above the charge in the transaction currency is refused without crediting, one above it only in the settlement currency posts, a second chargeback on the case debits again as pre-arbitration, a final line closes the case with the scheme's outcome and moves no money, and a chargeback on a closed agreement posts nothing and raises a task
# Seen at: route:/merchant-chargebacks/{id}
# Bite 4
Scenario: a representment is recorded and the clock is watched
Given a received chargeback due in five days and warning days of five
When day-end runs, and a clerk records the merchant's evidence as represented
Then a follow-up task is raised to the acquiring disputes group, and the case moves to represented with the date the scheme's answer is expected
And a received case past its due date reads overdue the next day, is not closed by the clock, and stops reading overdue once represented
# Seen at: route:/merchant-chargebacks/{id}
# Bite 4
Scenario: a clerk accepts a case for the merchant
Given a chargeback at pre-arbitration and another reversed
When a clerk accepts each for the merchant, and a second clerk approves
Then the first closes lost, and the reversed case cannot be accepted
# Seen at: route:/merchant-chargebacks/{id}
# Bite 5
Scenario: a merchant over both thresholds has its reserve stepped up from the first of the month
Given an agreement stepping a 5% reserve up to 10% at a ratio of 2% and a count of 2
When the first business day of the month runs after a month of 100 sales and 3 chargebacks
Then the ratio 3% is recorded and the terms carry a 10% reserve from that day, naming the counts
And a month of 100 sales and 1 chargeback records the ratio and changes nothing, a month with chargebacks and no sales counts as over, and a step-up on a T+0 agreement is refused when the terms are amended
# Seen at: route:/merchant-agreements/{id}
# Bite 6
Scenario: an operator follows a chargeback from the feed to the reserve it consumed
Given the sample merchant's chargeback
When an operator opens the agreement's chargebacks list, the case, and the agreement's reserve panel
Then the list shows the case, the case shows its stage, reason, due date and money, and the reserve shows the day it consumed
# Seen at: route:/merchant-chargebacks/{id}
Scenario → test
| Scenario | Bite | Project | Class | Method | Probe |
|---|---|---|---|---|---|
| a reserve day reduces the settlement account’s available balance wherever it is read | 1 | LedgerTM.Tests.Component |
MerchantReserveReductionTests |
a_reserve_day_reduces_the_settlement_accounts_available_balance_wherever_it_is_read |
— |
| a rolling reserve withholds a day’s percentage as its holds release and returns it on its date | 2 | LedgerTM.Tests.Component |
MerchantReserveTests |
a_rolling_reserve_withholds_a_days_percentage_as_its_holds_release_and_returns_it_on_its_date |
adr-843-server-probe.ts |
| a fixed reserve builds to its target and is held until after termination | 2 | LedgerTM.Tests.Component |
MerchantReserveTests |
a_fixed_reserve_builds_to_its_target_and_is_held_until_after_termination |
— |
| a chargeback debits the merchant and its fee, and the reserve bears what the free balance cannot, oldest first | 3 | LedgerTM.Tests.Component |
MerchantChargebackTests |
a_chargeback_debits_the_merchant_and_its_fee_and_the_reserve_bears_what_the_free_balance_cannot_oldest_first |
adr-843-server-probe.ts |
| a reversal returns the amount and keeps the fee | 3 | LedgerTM.Tests.Component |
MerchantChargebackTests |
a_reversal_returns_the_amount_and_keeps_the_fee |
— |
| a representment is recorded and the clock is watched | 4 | LedgerTM.Tests.Component |
MerchantChargebackDeadlinesTests |
a_representment_is_recorded_and_the_clock_is_watched |
adr-843-server-probe.ts |
| a clerk accepts a case for the merchant | 4 | LedgerTM.Tests.Component |
MerchantChargebackDeadlinesTests |
a_clerk_accepts_a_case_for_the_merchant |
— |
| a merchant over both thresholds has its reserve stepped up from the first of the month | 5 | LedgerTM.Tests.Component |
MerchantDisputeMonitoringTests |
a_merchant_over_both_thresholds_has_its_reserve_stepped_up_from_the_first_of_the_month |
— |
| an operator follows a chargeback from the feed to the reserve it consumed | 6 | LedgerTM.Tests.Component |
MerchantChargebackViewerTests |
the_chargeback_and_the_reserve_reads_carry_the_stage_the_money_and_the_day_consumed |
adr-843-server-probe.ts |
UI-surface sweep
Swept src/ui-apps/bank/src for reserve, chargeback, MerchantChargeback, ClaimId,
claims:
features/accounts/…show the account detail’s available balance, which the reserve reduces through the reductions; no claim origin is added, so no label changes.- No acquiring surface yet (ADR-842 bite 4 adds the agreement viewer); bite 6 adds two panels to it and the case viewer.
- Permission keys: every new key lands in
permissions.generated.tsthrough the catalog.
Footprint
Feature projects touched: 9 — LedgerTM.Accounts, LedgerTM.Cards, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure.Contracts, LedgerTM.Seeding.Provisioning, LedgerTM.Seeding.ZaRetail.Samples, LedgerTM.Tasks, ui-apps
LedgerTM.Accounts— 2 changed, 0 newLedgerTM.Cards— 1 changed, 0 newLedgerTM.Contracts— 7 changed, 0 newLedgerTM.Hosting— 1 changed, 0 newLedgerTM.Infrastructure.Contracts— 1 changed, 0 newLedgerTM.Seeding.Provisioning— 1 changed, 0 newLedgerTM.Seeding.ZaRetail.Samples— 1 changed, 0 newLedgerTM.Tasks— 2 changed, 0 newui-apps— 2 changed, 0 new Files: 59 named, 50 code, 3 config
Contracts types: 44 named, 39 changed by this ADR
ICommand— fan-in 38, referenced (LedgerTM.Accounts, LedgerTM.Attachments, LedgerTM.Audit, LedgerTM.Authorisation, LedgerTM.BankStatements, LedgerTM.Books, LedgerTM.Cards, LedgerTM.ClientChannel, LedgerTM.Collections, LedgerTM.Compliance, LedgerTM.Contracts, LedgerTM.Correspondence, LedgerTM.Counterparties, LedgerTM.Currencies, LedgerTM.DayEnd, LedgerTM.DocumentTemplates, LedgerTM.Identifications, LedgerTM.Import, LedgerTM.Infrastructure, LedgerTM.Infrastructure.Contracts, LedgerTM.Limits, LedgerTM.Metering, LedgerTM.OperatingEntities, LedgerTM.Payments, LedgerTM.Pricing, LedgerTM.[redacted], LedgerTM.Regulatory, LedgerTM.Securities, LedgerTM.Seeding.[redacted].Conversion, LedgerTM.ServiceEnrolment, LedgerTM.Signing, LedgerTM.Statements, LedgerTM.Structures, LedgerTM.Suspense, LedgerTM.Tasks, LedgerTM.Tax, LedgerTM.Warehouse, ui-apps)ISystemCommand— fan-in 31, referenced (LedgerTM.Accounts, LedgerTM.BankStatements, LedgerTM.Books, LedgerTM.Cards, LedgerTM.ClientChannel, LedgerTM.Collections, LedgerTM.Compliance, LedgerTM.Contracts, LedgerTM.Correspondence, LedgerTM.Counterparties, LedgerTM.DayEnd, LedgerTM.Identifications, LedgerTM.Identity, LedgerTM.Import, LedgerTM.Infrastructure, LedgerTM.Infrastructure.Contracts, LedgerTM.Limits, LedgerTM.Metering, LedgerTM.OperatingEntities, LedgerTM.Payments, LedgerTM.Pricing, LedgerTM.Regulatory, LedgerTM.Scheduling, LedgerTM.Seeding.[redacted].Conversion, LedgerTM.ServiceEnrolment, LedgerTM.Signing, LedgerTM.Statements, LedgerTM.Suspense, LedgerTM.Tasks, LedgerTM.Tax, LedgerTM.Warehouse)TransactionSource— fan-in 6, referenced (LedgerTM.Accounts, LedgerTM.Books, LedgerTM.Contracts, LedgerTM.Payments, LedgerTM.Tax, ui-apps)AttachmentId— fan-in 2, referenced (LedgerTM.Attachments, _creditplus)ExternalIntegrations— fan-in 1, referenced (LedgerTM.Accounts)AcceptMerchantChargebackCommand— fan-in 0, changedAcquiringReductionsReader— fan-in 0, changedCardDisputeReasonCodeView— fan-in 0, changedChargebackMoney— fan-in 0, changedGetMerchantChargebackQuery— fan-in 0, changedGetMerchantReserveQuery— fan-in 0, changedICardDisputeReasonCodeReader— fan-in 0, changedListMerchantChargebacksQuery— fan-in 0, changedMerchantChargeback— fan-in 0, changedMerchantChargebackApproverViewReader— fan-in 0, changedMerchantChargebackDeadlinesStep— fan-in 0, changedMerchantChargebackId— fan-in 0, changedMerchantChargebackIsItsOwnHolder— fan-in 0, changedMerchantChargebackOutcome— fan-in 0, changedMerchantChargebackStage— fan-in 0, changedMerchantChargebackSummary— fan-in 0, changedMerchantReserveBalance— fan-in 0, changedMerchantReserveDay— fan-in 0, changedMerchantReserveDayId— fan-in 0, changedMerchantReserveDayView— fan-in 0, changedMerchantReserveOutstanding— fan-in 0, changedMerchantReserveView— fan-in 0, changedMonitorMerchantDisputesCommand— fan-in 0, changedMonitorMerchantDisputesStep— fan-in 0, changedPostMerchantChargebackLineCommand— fan-in 0, changedProcessMerchantChargebackCommand— fan-in 0, changedProcessMerchantChargebackReversalCommand— fan-in 0, changedRecordMerchantRepresentmentCommand— fan-in 0, changedReleaseMerchantReserveCommand— fan-in 0, changedReleaseMerchantReserveStep— fan-in 0, changedRequestMerchantChargebackFollowUpTaskCommand— fan-in 0, changedReserveConsumption— fan-in 0, changedReserveKind— fan-in 0, changedReserveMerchantSettlementCommand— fan-in 0, changedReserveMerchantSettlementStep— fan-in 0, changedReserveRule— fan-in 0, changedReserveTarget— fan-in 0, changedStepUpRule— fan-in 0, changedWatchMerchantChargebackDeadlinesCommand— fan-in 0, changed
Files reading each changed type: 39 types
AcceptMerchantChargebackCommand— 0 filesAcquiringReductionsReader— 0 filesCardDisputeReasonCodeView— 0 filesChargebackMoney— 0 filesGetMerchantChargebackQuery— 0 filesGetMerchantReserveQuery— 0 filesICardDisputeReasonCodeReader— 0 filesListMerchantChargebacksQuery— 0 filesMerchantChargeback— 0 filesMerchantChargebackApproverViewReader— 0 filesMerchantChargebackDeadlinesStep— 0 filesMerchantChargebackId— 0 filesMerchantChargebackIsItsOwnHolder— 0 filesMerchantChargebackOutcome— 0 filesMerchantChargebackStage— 0 filesMerchantChargebackSummary— 0 filesMerchantReserveBalance— 0 filesMerchantReserveDay— 0 filesMerchantReserveDayId— 0 filesMerchantReserveDayView— 0 filesMerchantReserveOutstanding— 0 filesMerchantReserveView— 0 filesMonitorMerchantDisputesCommand— 0 filesMonitorMerchantDisputesStep— 0 filesPostMerchantChargebackLineCommand— 0 filesProcessMerchantChargebackCommand— 0 filesProcessMerchantChargebackReversalCommand— 0 filesRecordMerchantRepresentmentCommand— 0 filesReleaseMerchantReserveCommand— 0 filesReleaseMerchantReserveStep— 0 filesRequestMerchantChargebackFollowUpTaskCommand— 0 filesReserveConsumption— 0 filesReserveKind— 0 filesReserveMerchantSettlementCommand— 0 filesReserveMerchantSettlementStep— 0 filesReserveRule— 0 filesReserveTarget— 0 filesStepUpRule— 0 filesWatchMerchantChargebackDeadlinesCommand— 0 files Implementations of changed types: 0 Files reading a touched file by path: 3Bootstrapper.cs—src/LedgerTM.Accounts/Application/Commands/ProcessDayEnd.cs,src/LedgerTM.Books/Application/Commands/PostTransaction.cs,src/LedgerTM.Infrastructure.Contracts/LedgerTM.Infrastructure.Contracts.csproj,src/_creditplus/docs/superpowers/plans/2026-03-14-rook-phase1-foundation.md,src/_creditplus/docs/superpowers/plans/2026-03-15-multitenant-bootstrap.md,src/_creditplus/docs/superpowers/plans/2026-03-15-phase2-multitenancy-auth.md,src/_creditplus/docs/superpowers/plans/2026-03-15-phase3-ui-commands-batch.md,src/_creditplus/docs/superpowers/plans/2026-03-17-data-init-saga-workers.md,src/_creditplus/docs/superpowers/plans/2026-03-20-ui-polish-crud-validation.md,src/_creditplus/docs/superpowers/specs/2026-03-14-rook-option1-design.md,src/_creditplus/docs/superpowers/specs/2026-03-15-multitenant-bootstrap-design.md,src/_creditplus/docs/superpowers/specs/2026-03-17-data-init-saga-workers-design.mdPostingSettings.yaml—LedgerTM.Tests.Architecture/ProductPackageNamesNoCountryTests.cs,LedgerTM.Tests.Component/Books/FxRevaluationBookingTests.cs,LedgerTM.Tests.Component/Books/InterestPaidPostingRuleTests.cs,LedgerTM.Tests.Component/Books/WithheldCapitalisationPostingRuleTests.cs,LedgerTM.Tests.Component/Seeding/PackageImporterFolderTests.cs,LedgerTM.Tests.Component/Seeding/RetainedEarningsTemplateTypeTests.cs,LedgerTM.Tests.Reconciliation.[redacted]/CurrencyTransactionFxImportTests.cs,LedgerTM.Tests.Reconciliation.[redacted]/CurrencyTransactionParityTests.cs,LedgerTM.Tests.Unit/Books/NegativeInterestPostingRuleTests.cs,LedgerTM.Tests.Unit/Books/PostingRuleCoverageTests.cs,LedgerTM.Tests.Unit/[redacted]/AuthoredOverlayTests.cs,LedgerTM.Tests.Unit/[redacted]/FxRevaluationTemplateTests.cs,LedgerTM.Tests.Unit/[redacted]/[redacted].cs,LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt,src/LedgerTM.Seeding.Provisioning/PackageExporter.cs,src/LedgerTM.Seeding.Provisioning/PackageImporter.cs,src/LedgerTM.Seeding.Provisioning/PackageModel.cs,src/LedgerTM.Seeding.[redacted].Conversion/Steps/DealImport/PostingRuleCatalog.cs,src/LedgerTM.Seeding.[redacted].Samples/Bootstrapper.cs,src/LedgerTM.Seeding/Packages/ReferenceCheck.cs,src/LedgerTM.Seeding/Packages/VocabularyRegistry.csapp.tsx—src/ui-apps/bank/index.html,src/ui-apps/bank/src/__tests__/features/account-types/account-types-tabs.test.tsx,src/ui-apps/bank/src/__tests__/features/settings/settings-list-tabs.test.tsx,src/ui-apps/bank/src/__tests__/route-guard-helpers.ts,src/ui-apps/bank/src/__tests__/route-tree.ts,src/ui-apps/bank/src/__tests__/theme-boot-script.test.ts,src/ui-apps/bank/src/__tests__/window-location-guard.test.ts,src/ui-apps/bank/src/components/layout/rail-nav.tsx,src/ui-apps/bank/src/features/counterparties/flyout-config.ts,src/ui-apps/bank/src/lib/api.ts,src/ui-apps/bank/ui-review/targets/resolve-targets.ts,src/ui-apps/shared/lib/theme-key.ts
Domain events touched: 15 — MerchantChargebackClosed, MerchantChargebackMoneyRecorded, MerchantChargebackOverdue, MerchantChargebackReceived, MerchantChargebackReopened, MerchantChargebackRepresented, MerchantChargebackReserveConsumed, MerchantDisputeRatioRecorded, MerchantReserveConsumed, MerchantReserveDateSettled, MerchantReserveReleased, MerchantReserveShortfallRecorded, MerchantReserveSteppedUp, MerchantReserveWithheld, MerchantSalesPostedForDate Aggregates touched: 0
Methods at CRAP 30+ in changed files: 2 (unit coverage at main 34a04572b)
LedgerTM.Accounts.Application.Commands.ExternalSourceDispatcher.BuildEvaluationContext— CRAP 506, complexity 22, 0% covered —src/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.csExternalSourceDispatcher.DispatchAsync— CRAP 420, complexity 20, 0% covered —src/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.csPermission keys to add: 15 — accept-merchant-chargeback, i, i-system, monitor-merchant-disputes, post-merchant-chargeback-line, process-merchant-chargeback, process-merchant-chargeback-reversal, record-merchant-representment, release-merchant-reserve, request-merchant-chargeback-follow-up-task, reserve-merchant-settlement, watch-merchant-chargeback-deadlines, get-merchant-chargeback-query, get-merchant-reserve-query, list-merchant-chargebacks-query
Warnings
- A domain event is touched — set
reseed: trueand say so in the plan. LedgerTM.Accounts.Application.Commands.ExternalSourceDispatcher.BuildEvaluationContextis at CRAP 506 (and 1 more in that file) — write its test before the bite edits it, and name the test in the plan.- 9 feature projects touched — say why this is not two ADRs.
At land: 85 files touched, 59 predicted, 47 unplanned. LedgerTM.Tests.Architecture/CascadedMoneyMoveTests.cs, LedgerTM.Tests.Architecture/FeatureProviderSeamTests.cs, LedgerTM.Tests.Architecture/SessionAcquisitionConfinementTests.cs, LedgerTM.Tests.Architecture/UnitOfWorkTests.cs, LedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txt, LedgerTM.Tests.Component/Acquiring/AcquiringComponentFixture.cs, LedgerTM.Tests.Component/Acquiring/AcquiringFeedTests.cs, LedgerTM.Tests.Component/Seeding/SampleMerchantSeedTests.cs, LedgerTM.Tests.Unit/AccessControl/PermissionKeyPinTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Accounts/Application/Settings/ExternalIntegrationsValidator.cs, src/LedgerTM.Accounts/Domain/Account.Posting.cs, src/LedgerTM.Accounts/Domain/Configuration/ExternalIntegrations.cs, src/LedgerTM.Accounts/Yaml/ExternalIntegrationsYamlConverter.cs, src/LedgerTM.Acquiring/Application/AcquiringRoutes.cs, src/LedgerTM.Acquiring/Application/Agreements/AddMerchantSettlementCurrency.cs, src/LedgerTM.Acquiring/Application/Agreements/MerchantAgreementSummary.cs, src/LedgerTM.Acquiring/Application/Agreements/OpenMerchantAgreement.cs, src/LedgerTM.Acquiring/Application/Chargebacks/AcceptMerchantChargeback.cs, src/LedgerTM.Acquiring/Application/Chargebacks/GetMerchantChargeback.cs, src/LedgerTM.Acquiring/Application/DayEnd/AcquiringFeedPost.cs, src/LedgerTM.Acquiring/Application/DayEnd/PostMerchantChargebackLine.cs, src/LedgerTM.Acquiring/Application/Pricing/AcquiringPricingAttributes.cs, src/LedgerTM.Acquiring/Application/Reserve/AcquiringReductionsReader.cs, src/LedgerTM.Acquiring/Application/Reserve/MerchantReserveDayProjection.cs, src/LedgerTM.Acquiring/Bootstrapper.cs, src/LedgerTM.Acquiring/Domain/FreeBalance.cs, src/LedgerTM.Acquiring/Domain/MerchantAgreement.Events.cs, src/LedgerTM.Acquiring/Domain/MerchantAgreement.Monitoring.cs, src/LedgerTM.Acquiring/Domain/MerchantAgreement.Reserve.cs, src/LedgerTM.Acquiring/Domain/MerchantChargeback.Events.cs, src/LedgerTM.Acquiring/Domain/MerchantSettlementAccounts.cs, src/LedgerTM.Cards/Bootstrapper.cs, src/LedgerTM.Contracts/Accounts/Triggers/TransactionSource.cs, src/LedgerTM.Contracts/Acquiring/AcquiringFeed.cs, src/LedgerTM.Seeding.Provisioning/tenant-templates/countries/za/retail-bank/PriceSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/PostingSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/PriceSettings.yaml, src/ui-apps/bank/src/__tests__/standard-table-rowhref-guard.test.ts, src/ui-apps/bank/src/app.tsx, src/ui-apps/bank/src/features/acquiring/acquiring-feed-batches-panel.tsx, src/ui-apps/bank/src/features/acquiring/hooks.ts, src/ui-apps/bank/src/features/acquiring/merchant-agreement-viewer.tsx, src/ui-apps/bank/src/features/acquiring/merchant-chargeback-dialogs.tsx, src/ui-apps/bank/src/features/acquiring/merchant-chargeback-viewer.tsx, src/ui-apps/bank/src/features/acquiring/merchant-chargebacks-panel.tsx, src/ui-apps/bank/src/lib/api.ts
Land batches
One land, the whole ADR; reseed: true. Every bite starts after ADR-842 lands, and after
ADR-840 for the reason codes and AttachmentId (F2).
Notes
- The free balance is the available balance with the uncleared-funds holds added back (D4).
- Consumed and released are kept apart on the reserve days, the read and the guide (D1).
- The reserve step runs after the walk and before the post step; a T+0 agreement cannot carry a reserve (D2).
- Fixtures. ADR-842’s acquiring fixture, with the reserve rule on the terms; chargeback lines are feed lines with a case reference; bite 1’s test appends the agreement’s declared reserve events, as ADR-840’s tests append a dispute’s.
- Settings shape.
AcquiringSettings’ warning days and group repeatCardDisputeSettings’ shape on purpose: the acquirer’s disputes desk is a different team. Flagged, not merged. - The dispatcher. Its two high-CRAP methods are not edited; bite 3 only adds two handlers,
covered by ADR-842’s external-source tests. “Aggregates touched: 0” in the footprint is the
script’s artefact:
MerchantChargebackis new and the agreement is ADR-842’s. - The guide articles name the schemes’ monitoring programmes and lift their numbers from
MerchantReserveTestsandMerchantChargebackTests.
Landing notes
- ADR-842:
MerchantAgreementTermsgainsReserveandStepUp;AcquiringFeedLinegainsReasonCode,OriginalProcessorReference,ChargebackOutcomeand the kindChargebackFinal;AcquiringSettingsgains the warning days and group; the post step records each date’s gross and hands chargeback lines to this ADR’s handling; the payout step skips an account with a released date not yet reserved; the agreement does not close with an open case. - ADR-837: its plan adds
AccountAvailability.FacilityAvailable; both members are trailing, and whichever lands second appends after the other. - ADR-836:
AccountAvailabilitygainsUnclearedFunds; Acquiring’s reductions reader joins Cards’ in the summed set. - ADR-840: Cards implements
ICardDisputeReasonCodeReaderover its reason-code settings. - Decided: the reserve documents are two inline
MultiStreamProjections (day by id, balance by account), not anEventProjection· rests on: D1; Marten’s load-and-store drops a same-batch write · wrong if:reserve_days_on_one_account_sum_and_a_spent_or_released_day_reduces_nothingreds. - Decided: a reserve day’s currency, and whether an account is a settlement account, are read back from
AccountId.ForMerchantSettlement’s derived id (MerchantSettlementAccounts, in Acquiring) · rests on: the plan’s “an account id without ForMerchantSettlement’s prefix → zero” · wrong if: a settlement account id stops ending in its currency code. - Decided:
ProcessMerchantChargebackCommand,ProcessMerchantChargebackReversalCommandandRequestMerchantChargebackFollowUpTaskCommandmove from bite 1 to bite 3, beside their handlers · rests on:PermissionCatalogTestspins a key only to a handled message · wrong if: a bite-1 or bite-2 test names them. - Decided: bite 1’s acceptance test rides bite 1’s commit, the rest ride
[Measure]· rests on: the bite’s criterion is its passing run · wrong if:/ltm-landneeds every authored test in[Measure]. - Decided: bite 1’s author was re-dispatched three times for fixture defects (a stale settings cache, a test contradicting its own theory on a euro target, an unfunded account with no books); the authored file under
docs/is the re-authored one · rests on: ADR-787 step 6 · wrong if: the land’s copy differs fromdocs/adr/ADR-843-tests/bite-1.cs.txt. - Decided: adding a settlement currency checks the terms in force on its date and every later row, never earlier ones (the author’s “Reading A”) · rests on: plan ## Interfaces “every terms row in force on or after its date” · wrong if: an agreement with an expired fixed rule cannot gain a currency.
- Decided:
[Measure]copies no tests in. Bites 2–6’s tests each name a type only their own bite creates (GetMerchantReserveQuery,ProcessMerchantChargebackCommand,RecordMerchantRepresentmentCommand,MonitorMerchantDisputesCommand,ListMerchantChargebacksQuery), so every criterion starts red by compile and none can start green; each file is copied in with its bite · rests on: ADR-787 D5 (only a green start is probed) · wrong if: a later test compiles on bite 1’s tree. - Decided: the payout skips an account while a reserve-ruled date has released unreserved; a date counts as released when its release date is before the payout date, or on it with no uncleared funds left on the account · rests on: D2 “the payout step pays nothing from an account with a business date released and not yet reserved”; the payout opens the day after the walk · wrong if: a merchant with a hold releasing on the payout date and another later is held back a day (the uncleared-funds figure is per account, not per date).
- Decided: the agreement’s reserve state (dates and days) lives on the event-sourced aggregate, read live; the withholding rule is
MerchantAgreement.ReserveSettlement, the step passes it the available balance · rests on: CLAUDE.md no logic in handlers · wrong if: agreement streams grow long enough that live aggregation is slow. - Decided: a list query
ListReservingMerchantAgreementsQuery(acquiring.list-reserving-merchant-agreements) feeds both reserve steps every agreement not closed · rests on: D2 “whatever the agreement’s status since” · wrong if: a suspended agreement’s released date goes unreserved. - Decided: bite 2’s author was re-dispatched twice for arrange defects (sales dated before the agreement opened, a missing Current row, a walk run outside its saga); a stale
usingfrom ADR-784’s namespace move was corrected in every authored file by hand, a rename that changes no assertion · rests on: ADR-787 step 6 · wrong if: the land’s copies differ fromdocs/adr/ADR-843-tests/. - Decided: the availability reader keeps ADR-837’s floor at zero; the free balance is read from its unfloored members,
Ledger - (Claims - UnclearedFunds) - ExternalReductions(FreeBalance.Of) · rests on: ADR-837 ## Interfaces “Available = max(0, …)”, pinned byCardAuthorisationOverdraftTests.an_overdrawn_account_on_a_frozen_overdraft_reads_nothing_available· wrong if: a screen or a later ADR needs the reader itself to show a merchant’s debt. Bite 3’s author was re-dispatched to assert the debt this way. - Decided:
CASE_REOPENEDandREASON_CODE_UNKNOWNsit onAcquiringFeedOutcomes, as ## Interfaces places them, though they are notes · rests on: the plan’s interface · wrong if: a note reader looks for them onAcquiringFeedNotes. - Decided: a chargeback-family line with no case reference is
CASE_REFERENCE_MISSING, reversals and finals included; the reference check runs before the case lookup · rests on: plan ## Interfaces’ per-line order · wrong if: a reversal with no reference should wait asCASE_UNKNOWN. ADR-842’s feed test was re-dispatched to its author for this. - Decided:
MerchantChargebackReceivedcarries two trailing members beyond ## Interfaces,SchemeReasonCodeandReasonLabel, so the summary holds the raw code and the label the plan’s summary names · rests on: D3 ruled at phase B “keeps the scheme’s raw reason code beside the typed one” · wrong if: the label should follow a later vocabulary edit (it is captured at receipt). - Decided: a reversal or final routed to a closed agreement records
AGREEMENT_CLOSED(terminal) and raises no task; only a chargeback line opens a case and a task there · rests on: D3 ruled at the plan grill names only the chargeback · wrong if: a reversal on a closed agreement should reach the bank too. - Decided: a stray
using LedgerTM.Contracts.Properties;was removed from bite 3’s authored test (it madePropertyValueambiguous) · rests on: the stored event carriesInfrastructure.Contracts.Domain.PropertyValue· wrong if: the land’s copy differs fromdocs/adr/ADR-843-tests/bite-3.cs.txt. - Decided: the accept records the maker through
ApplicationContext.AttributedUserId, since an approved command replays under the system · rests on: D5 ruled at phase B “the closer is the maker” · wrong if:MerchantChargebackClosed.Byreadssystemor the approver after a four-eyes accept. - Decided: the accept’s stage check is its validator, an async read of the case summary, so a reversed or closed case is refused before capture; the aggregate checks again on apply · rests on: D5 ruled at phase B · wrong if: a reversed case’s accept answers 202.
- Decided: the case and the reserve day get document label resolvers, so a checker never reads their raw ids · rests on: ADR-780 D8 (
ReviewabilityTests) · wrong if: an approver panel shows amerchant_chargebackURN. - Decided: authored tests’
usings were moved to ADR-784’sLedgerTM.Authorisation.Countersign.*namespaces in bites 4–6 · rests on: the namespace move on main · wrong if: the land’s copies differ fromdocs/adr/ADR-843-tests/. - Midpoint box run (
/ltm-test, dad31a6d6): every test stage green; reachability red only forGetMerchantChargebackEndpointandListMerchantChargebacksEndpoint, which bite 6’s viewer test dispatches over HTTP. - Decided: monitoring counts from the feed batches’ posted sale lines (by the outcome’s agreement) and from the cases’ opening business dates, so no counting event is added · rests on: D6 ruled at phase B “counts by their batches’ business dates” · wrong if: a batch document is purged before its month is recorded.
- Decided: every completed month from the agreement’s first is recorded, an empty month as an empty ratio list, so a late batch never re-opens it · rests on: D6 “a month is recorded once” · wrong if: the event stream’s empty months matter to a reader.
- Decided:
MerchantReserveSteppedUpalone dates the stepped terms row (the aggregate and the summary each derive it as the terms in force with the stepped reserve), not a secondMerchantAgreementTermsAmended· rests on: D6 ruled at phase B “the step-up is the system’s own verb on the agreement” · wrong if: a terms-history reader expects every row to come from a terms amendment. - Decided: the reserve and chargeback reads answer on the bus whatever the feature, and over HTTP they throw
FeatureDisabledExceptionwhencards.acquiringis off (AcquiringRoutes); their keys are not bound inFeatureCatalog, because a bound key gates the bus too · rests on: ## Interfaces “The bus queries are ungated; the HTTP routes carry FeatureRoute cards.acquiring” (no such attribute exists) · wrong if: a later ADR adds a route-level feature attribute and two mechanisms answer one question. - Decided: the case route decodes its id (
Uri.UnescapeDataString), because the case id carries/and Wolverine hands the route parameter over still encoded · rests on: D3’s case id shape · wrong if: a case id ever contains a literal%. - Decided: the acquiring test fixture imports the retail package’s reason codes, as a tenant with acquiring has them · rests on: bite 6’s author assumption A3 · wrong if: a test relies on a tenant with no reason codes.
- Decided: the sample opens Boutique Bleu from yesterday with a 5% rolling reserve and stores yesterday’s batch (a 1 000.00 sale and a 30.00 chargeback, case VC-7731), which the next day-end posts; dated yesterday so the simulator’s own feed for today cannot replace it · rests on: plan bite 6 “the reserve rule and a sample chargeback” · wrong if: UAT finds no case on the sample agreement after one day-end. ADR-842’s sample seed test was re-dispatched to its author for the new terms.
- Decided: the aggregate keeps its own
MerchantChargebackLine;ChargebackMoneyis the read’s record, beside the summary, where ## Interfaces lists it · rests on: Domain never depends on Application · wrong if: the two drift in shape. - UAT (land-time, needs the stack): open Boutique Bleu after one day-end; the Chargebacks panel lists VC-7731, the case page shows its stage, clock and money, and the Reserve panel shows its days; the probe is
adr-843-server-probe.ts.