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
- The
merchantrole on aCompanycounterparty (retail templateRoleTypesSettings), with no agreement behind it. - The price card (ADR-841): a price chosen by selectors and bands,
fee(), the pricing attributes a dispatcher binds. Built to serve both sides of the card. - Claims (ADR-251): a dated hold against available balance; the external-source dispatcher
already raises an uncleared-funds claim on a deposit from
HoldReleaseOn. - Settlement instructions (ADR-115, ADR-187, ADR-414): an outbound payment is an instruction raised by the account, settled in its day-walk, paid over the rail ladder by service level, to an account nominated by a property role (ADR-231, ADR-264).
- Inbound files (
IInboundFileStore, ADR-820/836): a purpose, a business date, a mapper per connection, a simulator, day-end steps that simulate, fetch, import and post. IAccountAvailabilityReader(ADR-836): the available balance after claims, for a feature outside Accounts.- Books: per-rail settlement suspense and nostros (ADR-083 D6, ADR-094), statement reconciliation.
Scope
This ADR covers:
LedgerTM.Acquiring, a new feature project, and the merchant agreement aggregate: the merchant, its category, its processor identifiers, its pricing model, its settlement delay, its settlement account and its payout rule.- The acquiring feed: the canonical line and batch, the file purpose, the mapper per connection, the simulator, and the day-end steps that bring a day’s sales and refunds in.
- Pricing at receipt: each line priced by the price card as it is posted — interchange, scheme fee and acquirer margin as separate rows, blended as one — with the row hit recorded on the posting.
- The merchant settlement account type: gross credited on receipt with a claim that releases at T+n, fees debited on receipt, the GL legs.
- Payout by rail in the account’s currency, on the agreement’s frequency, to the nominated account, as a settlement instruction.
- The
cards.acquiringfeature key, so an acquirer that issues nothing and an issuer that acquires nothing each switch the other half off.
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
- A merchant agreement is a row of parameters, priced through the price card, settled through claims and instructions the platform already has. The two net-new pieces — the agreement and the feed — are the two an acquirer cannot do without.
- Priced at receipt, dated, so a repriced merchant never gets two rates on one day, and the statement shows the three components the EU Interchange Fee Regulation lets a merchant demand.
- The reserve is one more claim (ADR-843); nothing here is rebuilt for it.
- The acquiring half switches off for a tenant that issues only.
Negative / Trade-offs
- One settlement account per currency. A merchant settled in three currencies holds three accounts and is paid three times; the single-currency payout with FX is the FX settlement ADR.
- The delay counts business days on the payout rail’s calendar, from the batch’s business date, not the scheme’s; where the two differ the merchant is paid a day late or early against the scheme’s own settlement, which the receivable’s reconciliation shows.
- The feed is a file. A processor that streams is the fetch step’s adapter, not this ADR’s.
Neutral
- Chargebacks arrive on the same feed; until ADR-843 lands they are an exception on the batch,
as a
Chargebackclearing line is on the issuing side before ADR-840.
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.
- Decision 4 — the hold is on the net the dispatch credited, not the gross. A claim for the gross against a balance already net of fees made the available negative on every sale day; the deposit handler already holds exactly what it credited, said generally.
- Decisions 3 and 4 — the scheme’s cost is its own pair of rows, from what the line reports, under either model. The draft passed the merchant’s interchange through to the receivable, which left a blended merchant’s receivable unclearable and its income overstated.
- Decision 1 — the agreement is the one writer of the pricing model, setting every settlement account’s plan list dated; overrides answer a rate, terms answer the model. One model per agreement across currencies.
- Decision 3 — a line is priced and value-dated at its transaction date; the hold counts
from the batch’s business date. Per-item fees add, never floor. The refund charges
refund-feeand returns nothing; the scheme’s returned interchange reverses the cost rows. - Decision 3 — the settlement currency picks the account and the settlement amount is the
gross;
currency-conversionis the transaction currency differing from it. - Decisions 1 and 5 — suspended posts, terminated pays out whatever the minimum, an account the merchant owes on stays open; the step runs at the start of the day, so a Wednesday release pays Thursday; “at or above” the minimum.
- Decision 4 —
MerchantPayoutposts when the instruction settles, Books with it; Thursday raises the instruction. - Decision 2 — a re-import merges by reference as ADR-836’s post does; an unknown merchant’s line posts on a later re-post; a reported cost that differs from the priced one is a note.
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
- The per-item scheme fee as a floor or an addition.
- Which row prices the item fee on a refund.
- The agreement’s model vs the plan’s list.
- One model per agreement vs one plan per currency.
- Terms vs overrides for a merchant-specific rate.
- Priced at the line’s date vs at receipt.
- Value-dated the batch vs the transaction date.
- The hold from the batch date vs the scheme settlement date.
- A suspended agreement’s line: posts or an exception.
- A terminated agreement: walked or not.
- A terminated balance below the minimum.
- Available: the mechanism’s number vs the table’s.
- The release and the step on one day-end.
- The payout’s GL date.
- The blended receivable never clears.
- Interchange returned on a refund.
InterchangeChargedspelled two ways.
Phase A (acceptance-test author, 27 questions), 2026-10-02. The rulings that changed a decision:
- Decision 5 — the payout names its external account and value date, in the shape of the
standing-order payment, so the workflow raises a real instruction over the rail. The draft’s
payout-accountrole is gone from the platform (ADR-231 superseded by ADR-259); the agreement holds the payout account itself. - Decision 1 — the pricing model is an attribute,
pricing-model, with both models’ rows on one list per currency. A pricing plan’s list change is not value-dated, so a dated model switch through it was impossible; the agreement now writes the model alone. - Decision 1 — settlement accounts are provisioned through Accounts’
ProvisionAccountCommand, open and active, with the acquirer’s operating entity; the agreement readsClosedwhen its accounts stand at zero with nothing outstanding, and closing them is the bank’s ordinary close. - Decision 4 — the hold is the net credited, floored at zero; a sale whose charges exceed it
raises no claim. The release date comes from
ISettlementDateResolver.AddBusinessDays, a new method on the seam that owns rail calendars. Available may read below zero after a refund; the step pays nothing then, and the viewer shows the truth. - Decision 1 — priced on the transaction date’s terms, held on the business date’s; the delay is settlement, which runs from processing.
- Decision 2 — every amount positive, the kind the direction; a refund’s returned costs post
as their own
…Returnedtypes. Line ids derive from connection and processor reference, so a resent line posts once; the post step re-scans unposted lines (with no window, since the plan grill). - Decision 3 — no price-mismatch note; it needed a second pricing path outside Accounts.
- Decision 5 — the step’s date is the day the increment opened; a payout raised then is never past a cut-off. Identifiers are unique across every agreement not yet closed.
- Worked example in rand on EFT, which is what the rail carries; a domestic sale.
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.
- Decision 1 — a payout account per settlement currency, owned by the merchant, in that currency, on an account-number standard: one account for several currencies would have paid euros into a rand account, and an unchecked owner is the classic payout-change fraud.
- Decision 4 — the hold basis is named on the command; a debit order keeps holding its amount. The generalisation would have dropped the hold on every forward-valued debit order.
- Decision 1 — the provisioned account gets books, an owner, a priced plan and a number:
the default posting group, the merchant as owning party, a
PriceListReferenceproperty, a numbering scheme. Without the first, every posting would have reached no GL. - Decision 1 — the price list is named by its typed id per currency and checked through the Pricing read, which gains the list’s currency; lists have no key and live in country cells.
- Decision 7 —
cards.acquiring, a sibling ofcards.issuing. - Decisions 2 and 3 —
interchange-region,consumer-prepaid; the delay counts the nth business day strictly after the batch date. - Decision 1 — no balance-owing event; the account’s balance answers it. The agreement closes
no earlier than a 120-day tail after termination; a line for a closed agreement’s window is a
terminal
AGREEMENT_CLOSED, never re-routed to a new holder of the identifier, which is reserved by a unique document while the agreement is open. - Decision 4 — the sale’s trading date is the run date, so a late post never lands in a closed period; no memorandum positions and no statement schedule — the merchant statement is the transactions read until a formatted statement is asked for.
- Decision 5 —
$settlementExternalAccount, a guard on the payout, account-number payout accounts only; per-agreement and per-batch commands. - Decision 2 — the re-scan has no window, as ADR-836’s as built; a terminal outcome ends it.
- Decision 1 — clearance through
IClearanceStatusProvider, the only gate the provisioned account meets.
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:
- Decision 1 —
Fromup to thirty days back, so an excepted line can find its agreement; the identifier’s window is half-open; terms are a dated series read at read time; refusals before provisioning; the verbs’ allowed states. - Decision 4 — the merchant charges carry VAT; the transactions read gains properties and source reference, the hold its release date, so the statement and the release are readable.
- Decision 5 — a terminated agreement waits for its last claim; the payout’s rail fee nets from it; redelivery rests on the dispatcher fix filed with the coordinator.
- Decision 7 — the next payout date and the agreement’s batches are reads, not fields.
- Stale text struck — the feature key everywhere, the step-command names, the parameter name,
the settlement account id, the list key,
interchange-region, the re-scan window, F2 and F6.
Notes
- Depends on ADR-836 (
IAccountAvailabilityReader, the inbound-file steps’ shape, the dispatcher’s back-valued posting), ADR-839 (the dispatcher binding the price provider and the value date) and ADR-841 (the price card,fee(), the pricing bag), all Accepted. - Refactoring opportunity: ADR-836’s clearing post and this feed’s post share a shape — store, import, post with a re-scan, outcomes by reference — worth one shared component once both run.
- Standards: ISO 18245 names the merchant category; the EU Interchange Fee Regulation
(2015/751) is what the unblended statement serves and ADR-298’s limit rows would cap for an
EU tenant — a register row when a tenant claims it, not here. The schemes’ interchange
geographies name the
interchange-regionvalues. - The rolling reserve and the acquiring side of disputes follow in ADR-843; spend controls after.
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).