This is the decision record as it was written, grilled and shipped. It’s copied from our repository unedited, apart from customer, partner and bank names, which read [redacted]. It was written for the people and agents building the product, so expect internal shorthand, and the mistakes are left in.

ADR-842: Cards and Authorisation: merchant settlement and acquiring

Status: Shipped — 2026-10-03


Context

The Problem

An acquirer receives a merchant’s card sales from a processor, prices each one, pays the merchant the net amount after a delay, and holds a reserve against chargebacks. The product is a pricing engine in front of a settlement account with unusual parameters: a pricing model (interchange++ or blended), a settlement delay of T+n business days, a payout currency, a reserve, and dispute thresholds — every one a parameter on a merchant agreement, and every one sold by the incumbents as a professional-services project.

The platform has every mechanism but two. Rails, T+n value dating, available-balance claims, suspense, the counterparty with a merchant role, statement ingest and the attribute-banded price card (ADR-841) exist. What does not exist is the merchant agreement — the row of parameters — and the acquiring feed: the only new external interface, a daily file of priced transactions from the processor. This ADR builds those two and wires the rest. The reserve and the acquiring side of disputes are the next ADR; they sit on the agreement this one creates.

What Already Exists

Scope

This ADR covers:

Out of scope: the rolling and fixed reserve, chargebacks in the feed, the dispute-ratio step-up and the acquiring side of disputes (ADR-843, on this agreement); cross-currency payout — a merchant paid in one currency for sales in another — which is FX settlement, a later ADR (here, one settlement account per transaction currency, paid in that currency); interchange and scheme fees the acquirer pays the schemes (they pass through the scheme settlement receivable and reconcile against the scheme’s statement, ADR-094’s existing path); merchant onboarding workflow and due diligence (the counterparty’s compliance clearance gates the agreement as it gates issuance); a real acquiring processor’s adapter (the simulator and the mapper seam land; the adapter waits for the processor a buyer names); the merchant portal.


Decisions

1. The merchant agreement is an aggregate, and the parameters live on it

MerchantAgreement lives in LedgerTM.Acquiring with its own id (many per counterparty, ADR-314): the merchant counterparty (which must hold the merchant role and stand cleared and unfrozen under the tenant’s compliance clearance — the provisioned account bypasses activation’s own gate, so this check is the only one), the acquirer’s operating entity, the merchant category (ISO 18245, a MerchantCategoryCode), the processor identifiers the feed names it by (one or more, each with its connection, unique across every agreement not yet closed and kept as a dated history once closed), the settlement currencies — each with its own payout account (an external account captured for the merchant, ADR-413, owned by the merchant, in that currency, on an account-number standard), its own price list (named by its typed id, in that currency) and its own MerchantSettlementAccount the agreement provisions — the status (Active, Suspended, Terminated, Closed), and a dated series of terms: the pricing model (InterchangePlusPlus or Blended), the settlement delay in business days (0 to 30, the nth business day strictly after the batch’s business date, so a Saturday or Sunday batch at T+2 releases on Tuesday), the payout frequency (Daily, Weekly, Monthly) and the payout minimum. The reserve rules and dispute thresholds are ADR-843’s fields on the same aggregate.

Terms are amended with an effective date, from the start of that day, never earlier than the trading date. Two dates read them, each for its own question: a line is priced on the terms in force on its transaction date — so a repriced merchant gets one rate per line, never two — and held on the terms in force on its batch’s business date, since the delay measures settlement, which runs from processing. The pricing model reaches the price card as an attribute, pricing-model, in the line’s pricing bag: both models’ rows live on one price list per currency under that selector, so the agreement is the one writer of the model and a model switch is a dated amendment, with no price-list change on the account. A rate that differs for one merchant from the list is the pricing plan’s dated override or adjustment — terms answer which model and when paid, overrides answer what rate — and both show on the agreement viewer.

Verbs: Open (provisions, first, one active settlement account per currency through Accounts’ ProvisionAccountCommand — its id derived from the agreement and the currency, the account type’s default posting group so it has books, the merchant as its owning party, its pricing plan on the currency’s list — then starts the agreement, so a retry is safe), AddSettlementCurrency, AmendTerms, AmendPayoutAccount (per currency, the same ownership and currency checks), Suspend (the feed still posts; claims still release; payout stops), Resume, Terminate (the feed still posts what the scheme sends; once no claim remains the whole available is paid out whatever the minimum; an account below zero leaves the agreement Terminated, the account’s own balance showing the debt, recovery being ADR-843’s reserve and collections’; the agreement is Closed no earlier than the tenant’s closure tail — 120 days, the schemes’ common filing limit — after termination, and only when every account stands at zero with nothing outstanding; the accounts may then be closed by the bank’s ordinary close). A feed line naming an identifier no agreement carries is an exception on the batch; a line whose transaction date falls in a closed agreement’s window is the terminal outcome AGREEMENT_CLOSED, surfaced for the desk and never routed to whoever holds the identifier now.

Ruled at phase B. An agreement’s From may be up to thirty days before the trading date — a merchant onboarded after its first sales — and never after it; its identifiers’ history starts there, so a line excepted as an unknown merchant posts once an agreement covering its date is opened. A closed agreement’s window is [From, ClosedOn); a new holder of the identifier owns from ClosedOn. Terms form a dated series: each amendment governs from its date until the next dated one, whatever order they were recorded in, and a second amendment on the same date replaces the first; the agreement read computes the terms in force on the trading date at read time. Every refusal is checked before any account is provisioned; the unique reservation is the only race guard, and an open that loses that race leaves a provisioned settlement account at zero, never posted to, which a retried open with the same id adopts. Verbs: suspend needs Active, resume needs Suspended, amending terms or a payout account needs Active or Suspended, terminate needs Active or Suspended, and any verb on a terminated agreement is refused MERCHANT_AGREEMENT_TERMINATED; an open needs at least one settlement currency and no currency twice.

2. The feed is a canonical line, a purpose and a mapper, as the clearing feed is

AcquiringFeedLine carries what pricing and settlement need: the processor reference, the merchant identifier, the kind (Sale, Refund, Chargeback, ChargebackReversal, Adjustment — the last three posted by ADR-843; here they are an exception on the batch), the scheme, the card product (consumer-debit, consumer-credit, consumer-prepaid, commercial — the scheme’s product, distinct from ADR-841’s issuer card-type), the interchange region (domestic, intra-regional, inter-regional — the schemes’ interchange geography), the channel and entry mode (ADR-820’s vocabularies), the transaction amount and currency, the settlement amount and currency as the scheme settles it — every amount positive, the kind carrying the direction — the interchange and scheme fee the processor reported (optional, positive, the scheme’s take on a sale and what it returns on a refund), the DCC flag, the transaction date, the scheme settlement date (what the scheme will pay on; reconciliation reads it, settlement to the merchant does not), the authorisation code, and a property bag for what the contract does not name (ADR-694’s shape). An AcquiringFeedBatch is a connection’s lines for a business date, received through IInboundFileStore under purpose acquiring.feed, superseded by version as every inbound file is. A business date may be any trading date; the simulator writes on business days only, so its weekend sales arrive in Monday’s file.

A line’s transaction id derives from its connection and processor reference, as ADR-836’s does, so a line a processor resends in a later file posts once. A re-import of a day — the same file again, or a corrected version — merges outcomes by processor reference: a line already posted is never posted twice and a changed amount on it is noted LINE_AMENDED; a line new in the version posts; a line the version withdrew keeps its posting and is noted LINE_WITHDRAWN. The post step re-scans every batch holding an unposted line — an unknown merchant, a currency with no account, an Accounts refusal recorded as its code — and posts it once the cause is gone, as ADR-836’s post step does, with no window; a terminal outcome (AGREEMENT_CLOSED) ends a line’s re-scan. Each batch is its own post command and each agreement its own payout command, so one bad batch or agreement never fails the run.

An IAcquiringFeedMapper per connection turns the processor’s file into the canonical batch; the simulator’s mapper is the first, a real processor’s the next. Four day-end steps mirror the clearing feed’s at the next orders: simulate (51, RequiresSimulation, writing only when no file exists for the date), fetch (52), import (53), post (54), under feature key cards.acquiring, non-critical.

3. A line is priced when it is posted, at its own date, by the price card, with its attributes on the posting

The post step turns each Sale into ProcessMerchantSaleCommand to the agreement’s settlement account for the line’s settlement currency, for the settlement amount, value-dated the line’s transaction date (the day it was made; the type has no accruals to re-walk), with a pricing bag: pricing-model (the terms on the transaction date), scheme, card-product, interchange-region, channel, entry-mode, currency-conversion (the transaction currency differs from the settlement currency), dcc, merchant-category (the agreement’s). The price card answers at the value date. The account type’s acquiring-sale workflow posts the gross sale first and then the merchant’s charges through fee(), each its own transaction type: interchange, scheme-fee and acquirer-margin as Rate rows, and scheme-fee-per-item and acquirer-fee-per-item as Amount rows charged on top, never as floors. The blended rows of the list (pricing-model: blended) price every interchange and scheme row at 0 and acquirer-margin at the blended rate, so one workflow serves both models. The posting carries the bag as pricing. properties (ADR-841 D3), which with the fee rows is what the merchant statement and an IFR unblending request read.

The scheme’s own take is a second pair of rows on every sale, whatever the model: SchemeInterchangeCost and SchemeFeeCost, for the amounts the line reported, so the scheme settlement receivable carries what the scheme will actually pay, and a blended merchant’s margin is income gross of the scheme’s cost. A line reporting neither posts no cost rows — a zero posts nothing — and the batch records SCHEME_COST_UNREPORTED as a note on the line. Reported cost and charged price sit side by side on the posting; a report of the difference is a later read, not a second pricing path here.

A Refund posts ProcessMerchantRefundCommand to the same account: the gross refund debited first and refund-fee charged (an Amount row, 0 for a tenant that charges nothing); the merchant’s priced charges on the original sale are not returned, as the industry has it; the interchange and scheme fee the scheme returns, as the line reports them, post as SchemeInterchangeCostReturned and SchemeFeeCostReturned with the cost rows’ legs reversed. A refund is the scheme’s fact and posts whatever the balance; no refund is linked to its sale, since the scheme does not link them.

Ruled at phase B. Every leg of a sale’s dispatch carries the pricing bag, the cost rows included, as ADR-841 records it. SCHEME_COST_UNREPORTED means neither cost was reported; a reported zero is a reported zero. A merchant refund carries the bag, because refund-fee prices by it — ADR-841’s “a refund carries no bag” is the card refund’s. The bag’s values are the kebab-case of the contract’s enum names (ecommerce, keyed).

4. The settlement account credits gross on receipt, holds the net until T+n, and debits the fees

MerchantSettlementAccount is a liability account type in the acquiring layer, owned by the merchant, numbered by its own scheme: the position Current (what the merchant is owed); transaction types MerchantSale, MerchantRefund, InterchangeCharged, SchemeFeeCharged, SchemeFeePerItemCharged, AcquirerMarginCharged, AcquirerItemFeeCharged, RefundFeeCharged, SchemeInterchangeCost, SchemeFeeCost, SchemeInterchangeCostReturned, SchemeFeeCostReturned, MerchantPayout; no accruals, no interest.

The sale posts trading-dated the day the post runs — a line the re-scan posts later never lands in a closed period — and value-dated its transaction date. It carries the release date: the agreement’s delay in business days after the batch’s business date, on the calendar of the settlement currency’s payout rail — ISettlementDateResolver gains AddBusinessDays, over the scheduler’s existing business-day arithmetic, since the resolver owns which rail and so which calendar. The dispatcher then raises an uncleared-funds claim on Current for the net the dispatch credited to Current, floored at zero — 98.99 on the example’s 100.00 sale, before the charges’ VAT; no claim when the charges equal or exceed the sale, or when the delay is 0. The basis is the command’s choice, named on it: a merchant sale holds the net credited, a debit order keeps holding its amount, since a forward-valued debit order credits nothing at dispatch and a net rule would drop its hold. The claim releases in the account’s walk on its release date. Net settlement at T+n is therefore the claim releasing, and a sale never raises the available above what it credited.

A day whose refunds and charges exceed what has released takes the available below zero, and Current below zero when they exceed the balance — the merchant owes the acquirer, which later sales repay and ADR-843’s reserve secures; a claim the balance no longer covers reads unbacked, as ADR-251 D7 has it. The payout step pays nothing from an available at or below zero; the account viewer shows the true figure. The claim’s release is value-dated, replayable and visible on the account as every claim is, and the next ADR’s reserve is a second claim on the same money with a later date.

GL (PostingSettings): MerchantSale Dr Scheme settlement receivable / Cr Merchant payable; MerchantRefund the reverse; every merchant charge (InterchangeCharged, SchemeFeeCharged, the per-item rows, AcquirerMarginCharged, RefundFeeCharged) Dr Merchant payable / Cr Acquiring fee income; SchemeInterchangeCost and SchemeFeeCost Dr Acquiring cost of sales / Cr Scheme settlement receivable, and the …Returned rows the reverse (so the receivable is what the scheme pays, 99.59 on the example’s sale, under either model); MerchantPayout Dr Merchant payable / Cr the rail’s settlement suspense (ADR-083 D6), posted when the instruction settles (ADR-115: Books sees settled facts, once). The receivable is cleared by the scheme’s settlement arriving on the nostro statement and the suspense by the payout’s own arrival there, ADR-094’s reconciliation against the batch and instruction references — configuration, no new mechanism. A line left unposted is the difference that reconciliation shows until the post step’s re-scan posts it.

Ruled at phase B. The merchant charges are taxable fee rows under the tenant’s VAT, as every fee type is — a merchant service charge is a taxable supply in South Africa — so the charge’s tax slice posts with it; the worked example’s charges are shown net of VAT. A claim releasing on Wednesday is released in the day-end that closes Wednesday. The account’s transactions read gains each posting’s properties and source reference, and the account detail’s hold gains its release date, so the merchant statement — the sale and its charges, grouped by the line they share — and the hold’s release are read where the account is read.

5. Payout is a settlement instruction the agreement’s day-end step raises

MerchantPayoutStep (55, PostIncrement, non-critical, acquiring) runs at the start of each trading day — its date is the day the increment opened, as every post-increment step reads it — so a claim that released in Wednesday’s walk is paid in the step that opens Thursday, trading-dated Thursday. It walks the agreements that are active, or terminated and not closed, whose frequency falls due on the payout rail’s calendar — daily every business day, weekly the first business day of the ISO week, monthly the first business day of the month; a terminated agreement every business day; a resumed agreement on its next due day — and for each settlement account reads the available balance through IAccountAvailabilityReader (an account not active is skipped) and, where it is above zero and at or above the agreement’s minimum (one number, read in each account’s currency; a terminated agreement ignores it once the account holds no claim), dispatches ProcessMerchantPayoutCommand in the shape of ProcessStandingOrderPaymentCommand: that currency’s payout account, the trading date, and the value date the step resolves through ISettlementDateResolver.NextSettlementDate for the amount — the rail ladder chooses the rail (ADR-414), at the tenant’s default service level. The account’s merchant-payout workflow names that external account as its settlement ($settlementExternalAccount, the parameter the standing-order dispatch seeds), guarded by the available balance, so the step’s value date in the future raises a DirectCredit instruction (ADR-115, ADR-187). Raised at the start of the trading day, a payout is never past a rail’s cut-off. The instruction holds the amount as every outstanding instruction does and settles in the account’s day-walk at its value date, when MerchantPayout posts. A suspended agreement is skipped and its claims keep releasing. A payout is the account’s own withdrawal and so is guarded by the availability the claims leave; the step only chooses when.

Ruled at phase B. A terminated agreement pays nothing while any claim remains on the account, then pays the whole available whatever the minimum. Monthly is the first business day of the month. The payout’s rail fee, where the tenant prices one, is borne by the merchant — ADR-416’s creditor bearer — so it nets from the amount and the whole available still pays out. A payout redelivered before it settles raises nothing new: that rests on the external-source dispatcher refusing a transaction id already held by an outstanding instruction, a defect on main filed with the coordinator and named in the plan.

6. The simulator plays a processor

AcquiringSimulator (the simulated tenant, RequiresSimulation) writes a daily feed for every active agreement in the simulated tenant: a handful of sales across schemes, products, regions and channels, a refund now and then, with the processor-reported interchange and scheme fee set to what the retail price list would price, so reconciliation reads clean in a demo and a deliberate mismatch can be scripted.

7. Permissions, four-eyes and the screens

Opening, amending, suspending, resuming and terminating an agreement are user commands, four-eyes eligible and reviewable (MerchantAgreementApproverViewReader, SelfHoldingAggregate). The feed steps, the postings and the payout are system commands. The screens: a merchant agreements list and viewer (terms, settlement accounts, the last batches, the next payout), a feed batches panel with outcomes and exceptions, and the merchant settlement account’s own viewer showing the hold releases and the fee breakdown per sale. Feature key cards.acquiring, a sibling of cards.issuing, so a tenant switches acquiring on without issuing and one cards switch turns both off (ADR-065); permission keys stay acquiring.*. A preset composes one package, so the account type, the price types and rows, the posting rows and the connection live in the retail-bank package behind that key — licensed and off in za-retail, on in the simulated tenant; a standalone acquirer is a later package and preset for the buyer who names it.

Ruled at phase B. The agreement read carries the next payout date, computed at read time from the frequency and the payout rail’s calendar; the batches read filters by agreement, each outcome naming its agreement; there is no last-batch field on the agreement.


Contracts

Ids — MerchantAgreementId, AcquiringFeedBatchId (LedgerTM.Contracts/Acquiring).

Shapes (LedgerTM.Contracts/Acquiring) — the agreement’s PricingModel, PayoutFrequency, MerchantAgreementStatus, MerchantIdentifier, MerchantAgreementTerms, DatedTerms, MerchantSettlementCurrency and MerchantSettlementAccountRef; the feed’s AcquiringProcessorKind, AcquiringFeedLineKind, CardProduct, InterchangeRegion, AcquiringFeedLine, AcquiringFeedLineOutcome, AcquiringFeedBatch, AcquiringFeedOutcomes, AcquiringFeedNotes and AcquiringFeedPurposes.

Commands — OpenMerchantAgreementCommand, AddMerchantSettlementCurrencyCommand, AmendMerchantAgreementTermsCommand, AmendMerchantPayoutAccountCommand, SuspendMerchantAgreementCommand, ResumeMerchantAgreementCommand, TerminateMerchantAgreementCommand (LedgerTM.Acquiring, ICommand); SimulateAcquiringFeedCommand, FetchAcquiringFeedCommand, ImportAcquiringFeedCommand, PostAcquiringFeedBatchCommand, PayoutMerchantCommand (the steps’, ISystemCommand, the last two per batch and per agreement); ProcessMerchantSaleCommand, ProcessMerchantRefundCommand, ProcessMerchantPayoutCommand (LedgerTM.Contracts/Accounts, ISystemCommand, beside the card postings).

Events — on the agreement’s stream: MerchantAgreementOpened, MerchantAgreementTermsAmended, MerchantAgreementSuspended, MerchantAgreementResumed, MerchantAgreementTerminated, MerchantSettlementCurrencyAdded, MerchantPayoutAccountAmended, MerchantAgreementClosed.

Queries — GetMerchantAgreementQuery, ListMerchantAgreementsQuery, ListAcquiringFeedBatchesQuery, GetAcquiringFeedBatchQuery (IQuery<T>).

Consumed from LedgerTM.Contracts — IInboundFileStore, IAccountAvailabilityReader (ADR-836), IPriceProvider and PriceContext (ADR-841), ISettlementDateResolver (changed: AddBusinessDays), ProvisionAccountCommand, ProcessStandingOrderPaymentCommand (the payout’s shape), MerchantCategoryCode, CardChannel, CardEntryMode, ProcessDebitOrderPaymentCommand (the hold shape), ICounterpartyReferenceProvider.Standing (CounterpartyStanding.AssignedRoles, the role check), IClearanceStatusProvider.StandingForAsync (the clearance check), IPostingGroupReferenceProvider (the account’s books), GetPriceListReferenceQuery (changed: PriceListReference gains the list’s currency (a CurrencyId)), IScheduler (AddBusinessDays).

Changed — ExternalIntegrations gains AcquiringSale, AcquiringRefund, MerchantPayout; TransactionSource gains the three; FeatureCatalog gains cards.acquiring; PriceListReference gains the list’s currency (a CurrencyId); AccountId gains ForMerchantSettlement; ISettlementDateResolver gains AddBusinessDays; the external-source dispatcher’s uncleared-funds claim holds the net the dispatch credited, floored at zero.

ProcessCardFeeCommand is untouched; the merchant commands are added after it in the same file.

Removed — none.


Prior art

Declared Search returned Verdict
MerchantAgreement, MerchantAgreementId Card (ADR-835, a per-customer product aggregate), ChannelServiceAgreement (ADR-693, a counterparty’s agreement for a service), CollectionAuthority (ADR-713, a dated mandate) genuinely new — an agreement with priced terms, settlement accounts and a lifecycle; ADR-693’s is the nearest shape and is for a different service
AcquiringFeedLine, AcquiringFeedBatch, AcquiringFeedBatchId CardClearingItem, CardClearingBatch (ADR-820), ReportedLine (ADR-694) genuinely new beside them — the clearing line is the issuer’s view of one card; the acquiring line is a merchant’s sale with the scheme’s interchange geography and settlement amounts; ReportedLine is a bank statement line. The shape follows CardClearingBatch
IAcquiringFeedMapper IInboundMapper (ADR-820, per card processor) extend — the same seam for the acquiring processor
ProcessMerchantSaleCommand, ProcessMerchantRefundCommand, ProcessMerchantPayoutCommand ProcessCardPurchaseCommand, ProcessCardRefundCommand (ADR-836), ProcessBankDepositCommand (HoldReleaseOn) extend — the same shape with the pricing bag (ADR-841) and the hold
MerchantSettlementAccount CurrentAccount (ADR-837), SuspenseAccount (ADR-110), CorporateCurrentAccount genuinely new — an account type in YAML; no code
interchange, scheme-fee, acquirer-margin, scheme-fee-per-item, acquirer-fee-per-item, refund-fee ADR-841’s card fee rows, rtc-rail-fee (ADR-416) extend — price rows with selectors
MerchantPayoutStep, PayoutMerchantCommand MonthlyInterestPayment (ADR-231, a scheduled payout by role), RenewCardCredentialsStep (ADR-839) extend — a Cards-style step raising an account’s own payout workflow; a scheduled row cannot read the available balance across claims, the step can
the four feed steps SimulateCardClearingStep … PostCardClearingStep (ADR-836, 41–44) extend — the same four at 51–54
MerchantAgreementApproverViewReader CardApproverViewReader (ADR-835) extend — DocumentApproverViewReader over the summary
GetMerchantAgreementQuery, ListMerchantAgreementsQuery, ListAcquiringFeedBatchesQuery, GetAcquiringFeedBatchQuery GetCardQuery, ListCardClearingBatchesQuery (ADR-835/836) extend — the same reads for the agreement and the feed
MerchantAgreementOpened … MerchantSettlementCurrencyAdded CardIssued … (ADR-835) genuinely new — the agreement’s own stream
ProvisionAccountCommand Accounts’ derived-id open-and-activate (ADR-754) reuse — the settlement account is provisioned as suspense and disbursement accounts are
ProcessStandingOrderPaymentCommand an outbound payment naming its external account and value date reuse — the payout command’s shape
ProcessDebitOrderPaymentCommand the one external-source command carrying HoldReleaseOn reuse — the hold’s shape; its hold basis stays its amount
GetPriceListReferenceQuery, PriceListReference the price list read, id and description extend — gains the list’s currency, so a settlement currency’s list is checked
IPostingGroupReferenceProvider, IClearanceStatusProvider, IScheduler the posting group default, the compliance standing, business-day arithmetic reuse — the provisioned account’s books, the clearance gate, the hold’s calendar
AddMerchantSettlementCurrencyCommand, AmendMerchantPayoutAccountCommand, MerchantPayoutAccountAmended, MerchantAgreementClosed IAccountPayoutLimitGate (an unrelated gate), the card verbs (ADR-835) genuinely new — the agreement’s own verbs and events
ISettlementDateResolver.AddBusinessDays NextSettlementDate (rail lead days on the rail calendar) extend — the same calendar, an arbitrary count
IInboundFileStore, IAccountAvailabilityReader, IPriceProvider, PriceContext, ISettlementDateResolver, MerchantCategoryCode, CardChannel, CardEntryMode, ProcessBankDepositCommand, ICounterpartyReferenceProvider, CounterpartyStanding, ExternalIntegrations, TransactionSource, FeatureCatalog the seams as they are reuse — read or extended by a row

Relies on

Symbol What it does today What this ADR assumes
IInboundFileStore Receives a file by purpose and business date, superseding by version The feed’s store (D2)
ISettlementDateResolver The value date a payment clears, by rail lead days, on the rail’s calendar The payout instruction’s value date (D5); gains AddBusinessDays for the hold (D4)
ProvisionAccountCommand Opens and activates an account with a derived id, idempotently The settlement accounts (D1)
ICurrencyConverter Converts at the posted rate Not used: one account per currency (Scope)
SelfHoldingAggregate An aggregate holding its own change set for review (ADR-780) The agreement is one (D7)
IDayEndStep A step with an order, a phase and a criticality The five steps (D2, D5)
Claim A dated hold against available balance (ADR-251) The settlement delay (D4)

ADR-836’s IAccountAvailabilityReader and ProcessCardPurchaseCommand and ADR-841’s PriceContext, fee() and pricing bag are relied on as their plans declare them.


Worked example

Fixture: the simulated tenant with acquiring on; merchant Boutique Bleu (a Company with the merchant role, category 5651), agreement InterchangePlusPlus, delay T+2, daily payout, minimum 50, one ZAR settlement account on the retail rand acquiring list; price rows for { pricing-model: interchange-plus-plus, scheme: visa, card-product: consumer-credit, interchange-region: domestic }: interchange 0.30%, scheme-fee 0.05% with scheme-fee-per-item 0.06, acquirer-margin 0.50% with acquirer-fee-per-item 0.10, refund-fee 0.10; the processor reports interchange 0.30 and scheme fee 0.11 on the sale and returns 0.12 and 0 on the refund; a captured ZAR payout account on the EFT rail (T+1).

Date Feed Posting Current Available
Mon 2026-10-05 a 100.00 ZAR Visa consumer-credit e-commerce sale, domestic, made Sat 10-03 MerchantSale 100.00 value-dated 10-03; InterchangeCharged 0.30; SchemeFeeCharged 0.05; SchemeFeePerItemCharged 0.06; AcquirerMarginCharged 0.50; AcquirerItemFeeCharged 0.10; SchemeInterchangeCost 0.30 and SchemeFeeCost 0.11 against the receivable; a claim of 98.99 releasing Wed 10-07 98.99 0.00
Tue 10-06 a 40.00 ZAR refund MerchantRefund 40.00; RefundFeeCharged 0.10; SchemeInterchangeCostReturned 0.12 58.89 −40.10 (58.89 less the 98.99 still held; the payout step pays nothing)
Wed 10-07 — the claim releases in Wednesday’s walk 58.89 58.89
Thu 10-08 — MerchantPayoutStep opens the day: 58.89 ≥ 50 → a DirectCredit instruction of 58.89 raised to the payout account, value-dated Fri 10-09 (EFT T+1) 58.89 0.00 (the instruction holds it)
Fri 10-09 — the instruction settles: MerchantPayout 58.89; Books: Dr Merchant payable 58.89 / Cr EFT settlement suspense 0.00 0.00

The scheme settlement receivable after Monday reads 99.59, which is what the scheme pays.

The merchant’s statement line for the sale reads 100.00, interchange 0.30, scheme fee 0.11, margin 0.60, net 98.99 — interchange++ unblended. A blended merchant on the same list (pricing-model: blended) sees margin 0.91 and item fee 0.10 (every interchange and scheme row priced 0); its receivable still reads 99.59 and its margin income 1.01 gross of the 0.41 cost.


Model

Generated from docs/model/model.json (ADR-773 D8): the shape the model knows today, <<new>> for what ## Contracts declares and the model does not know, relies-on for ## Relies on. Regenerate with python3 scripts/model/adr_model.py ADR-NNN --write; frozen at Shipped.

classDiagram
  class PostingSettings {
    <<settings>>
  }
  class AcquiringFeedBatchId {
    <<new>>
  }
  class AcquiringRefund {
    <<new>>
  }
  class AcquiringSale {
    <<new>>
  }
  class AddBusinessDays {
    <<new>>
  }
  class AddMerchantSettlementCurrencyCommand {
    <<new>>
  }
  class AmendMerchantAgreementTermsCommand {
    <<new>>
  }
  class AmendMerchantPayoutAccountCommand {
    <<new>>
  }
  class FetchAcquiringFeedCommand {
    <<new>>
  }
  class ForMerchantSettlement {
    <<new>>
  }
  class GetAcquiringFeedBatchQuery {
    <<new>>
  }
  class GetMerchantAgreementQuery {
    <<new>>
  }
  class ImportAcquiringFeedCommand {
    <<new>>
  }
  class ListAcquiringFeedBatchesQuery {
    <<new>>
  }
  class ListMerchantAgreementsQuery {
    <<new>>
  }
  class MerchantAgreementClosed {
    <<new>>
  }
  class MerchantAgreementId {
    <<new>>
  }
  class MerchantAgreementOpened {
    <<new>>
  }
  class MerchantAgreementResumed {
    <<new>>
  }
  class MerchantAgreementSuspended {
    <<new>>
  }
  class MerchantAgreementTerminated {
    <<new>>
  }
  class MerchantAgreementTermsAmended {
    <<new>>
  }
  class MerchantPayout {
    <<new>>
  }
  class MerchantPayoutAccountAmended {
    <<new>>
  }
  class MerchantSettlementCurrencyAdded {
    <<new>>
  }
  class OpenMerchantAgreementCommand {
    <<new>>
  }
  class PayoutMerchantCommand {
    <<new>>
  }
  class PostAcquiringFeedBatchCommand {
    <<new>>
  }
  class ProcessMerchantPayoutCommand {
    <<new>>
  }
  class ProcessMerchantRefundCommand {
    <<new>>
  }
  class ProcessMerchantSaleCommand {
    <<new>>
  }
  class ResumeMerchantAgreementCommand {
    <<new>>
  }
  class SimulateAcquiringFeedCommand {
    <<new>>
  }
  class SuspendMerchantAgreementCommand {
    <<new>>
  }
  class TerminateMerchantAgreementCommand {
    <<new>>
  }
  class Claim {
    <<relies-on>>
  }
  class ICurrencyConverter {
    <<relies-on>>
  }
  class IDayEndStep {
    <<relies-on>>
  }
  class IInboundFileStore {
    <<relies-on>>
  }
  class ISettlementDateResolver {
    <<relies-on>>
  }
  class ProvisionAccountCommand {
    <<relies-on>>
  }
  class SelfHoldingAggregate {
    <<relies-on>>
  }

Consequences

Positive

Negative / Trade-offs

Neutral


Implementation Plan (Bites)

Four bites, one land; reseed: true. Bite 1 starts after ADR-841 batch A lands; bites 2–4 after ADR-836 lands too. Bites, acceptance criteria, files touched, and status live in ADR-842-plan.md.


Changed during the grill

Grilled 2026-10-02 by the author against ADR-836, ADR-841, ADR-251, ADR-115/187 and the press; the operator’s standing instruction was to take the recommendations.

Contradiction press: 17 pairs, resolved as above — 1, 2, 16 into Decision 3 (per-item rows, refund-fee, the cost rows); 3, 4, 5 into Decision 1 (one writer); 6, 7, 8 into Decision 3 (the line’s date, the batch’s date); 9 into Decision 1 (open, not active); 10, 11 into Decisions 1 and 5; 12, 13 into Decisions 4 and 5 (the net hold, the day boundary); 14 into Decision 4 (settled facts); 15 into Decisions 3 and 4 (the cost rows); 17 a spelling. The silent inputs — negative available, the unguarded refund, a refund larger than its sale or after termination, the refund’s legs, MerchantAdjustment (removed; ADR-843’s), where the per-item fee posts, the statement’s charges, blended per-item rows, currency choice, the minimum’s currency, the calendar, weekend batches, weekly and monthly days, “at or above”, the switch date, a corrected version, idempotency, the unknown merchant, the reported cost, suspension, termination owing, termination timing, the rail suspense, interest — are answered in Decisions 1 to 5.

Press block
  1. The per-item scheme fee as a floor or an addition.
  2. Which row prices the item fee on a refund.
  3. The agreement’s model vs the plan’s list.
  4. One model per agreement vs one plan per currency.
  5. Terms vs overrides for a merchant-specific rate.
  6. Priced at the line’s date vs at receipt.
  7. Value-dated the batch vs the transaction date.
  8. The hold from the batch date vs the scheme settlement date.
  9. A suspended agreement’s line: posts or an exception.
  10. A terminated agreement: walked or not.
  11. A terminated balance below the minimum.
  12. Available: the mechanism’s number vs the table’s.
  13. The release and the step on one day-end.
  14. The payout’s GL date.
  15. The blended receivable never clears.
  16. Interchange returned on a refund.
  17. InterchangeCharged spelled two ways.

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

Changed during the plan grill

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

Pressed and held: processor and scheme keys as strings; the markers; specificity of the seeded rows (no ties); every number of the worked example; the agreement-to-account reference; the payout id per account per day.

Changed during phase B

Four acceptance-test authors wrote 54 cold tests on 2026-10-02 (docs/adr/ADR-842-tests/). Their findings, folded as the “Ruled at phase B” paragraphs of Decisions 1, 3, 4, 5 and 7:

Notes

Outcome

Landed in four bites, as designed, with three security fixes made at bite boundaries. The three acquiring operations are system-only, and the payout step carries no feature key. The sale’s VAT is replayed net on a re-walk (37eb6734b). Two gaps were filed rather than fixed: a settled payout posts with source User (F-1881), and the agreement read needs the scheduler key (F-1882).