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

Files touched

Bite 1 — the contracts, the reserve days and their reduction

Bite 2 — the reserve

Bite 3 — chargebacks

Bite 4 — representment and clocks

Bite 5 — monitoring

Bite 6 — the screens, the sample, the probe, the guide

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:

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:

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

Contracts types: 44 named, 39 changed by this ADR

Files reading each changed type: 39 types

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)

Warnings

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

Landing notes