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-842 — Implementation Plan

Findings for the ADR

Files touched

Bite 1 — the project, the agreement, the package rows, the seam

Bite 2 — the feed, pricing and posting

Bite 3 — payout

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

Prior art

Changed since the grill: ProvisionAccountCommand (reuse, the settlement accounts) and ISettlementDateResolver.AddBusinessDays (extend) — both rows added to the ADR. The supporting shapes — MerchantIdentifier, MerchantAgreementTerms, DatedTerms, AcquiringFeedLineOutcome, AcquiringFeedOutcomes, AcquiringFeedPurposes — carry no decision.

Interfaces

// LedgerTM.Contracts/Acquiring/MerchantAgreement.cs — new (D1)
public readonly record struct MerchantAgreementId(string Value) : IStrongId<MerchantAgreementId> { … }   // Generate(); many per counterparty
public enum PricingModel { InterchangePlusPlus, Blended }            // in the bag as interchange-plus-plus | blended
public enum PayoutFrequency { Daily, Weekly, Monthly }
public enum MerchantAgreementStatus { Active, Suspended, Terminated, Closed }
public sealed record MerchantIdentifier(InstitutionConnectionId Connection, string Identifier);
public sealed record MerchantAgreementTerms(PricingModel PricingModel, int SettlementDelayBusinessDays, PayoutFrequency PayoutFrequency, decimal PayoutMinimum);   // delay 0..30, the nth business day strictly after the batch date; minimum >= 0 in each account's currency
public sealed record DatedTerms(MerchantAgreementTerms Terms, DateOnly EffectiveFrom);
public sealed record MerchantSettlementCurrency(CurrencyId Currency, ExternalAccountId PayoutAccount, PriceListId PriceList);
public sealed record MerchantSettlementAccountRef(CurrencyId Currency, AccountId Account, ExternalAccountId PayoutAccount);

// LedgerTM.Contracts/Acquiring/AcquiringFeed.cs — new (D2)
public readonly record struct AcquiringFeedBatchId(string Value) : IStrongId<AcquiringFeedBatchId> { … }   // For(connection, businessDate)
public enum AcquiringProcessorKind { Simulator }                    // the acquirer's processors, apart from the issuer's CardProcessorKind
public enum AcquiringFeedLineKind { Sale, Refund, Chargeback, ChargebackReversal, Adjustment }
public enum CardProduct { ConsumerDebit, ConsumerCredit, ConsumerPrepaid, Commercial }   // the scheme's product; ADR-841's card-type is the issuer's
public enum InterchangeRegion { Domestic, IntraRegional, InterRegional }
public sealed record AcquiringFeedLine(string ProcessorReference, string MerchantIdentifier, AcquiringFeedLineKind Kind, string Scheme, CardProduct CardProduct, InterchangeRegion InterchangeRegion,
    CardChannel Channel, CardEntryMode EntryMode, decimal Amount, CurrencyId Currency, decimal SettlementAmount, CurrencyId SettlementCurrency, decimal? ReportedInterchange, decimal? ReportedSchemeFee,
    bool Dcc, DateOnly TransactionDate, DateOnly SchemeSettlementDate, string? AuthorisationCode, string? SchemeCaseReference, IReadOnlyDictionary<string, string> ReportedProperties);   // every amount positive
public static class AcquiringFeedOutcomes { Posted = "POSTED", UnknownMerchant = "UNKNOWN_MERCHANT", AgreementClosed = "AGREEMENT_CLOSED" /* terminal */, NoSettlementAccountForCurrency = "NO_SETTLEMENT_ACCOUNT_FOR_CURRENCY", ChargebackNotHandled = "CHARGEBACK_NOT_HANDLED", AdjustmentNotHandled = "ADJUSTMENT_NOT_HANDLED" }   // an Accounts refusal records its own code
public sealed record AcquiringFeedLineOutcome(string ProcessorReference, string MerchantIdentifier, MerchantAgreementId? Agreement, string Outcome, TransactionId? Transaction, IReadOnlyList<string> Notes /* SCHEME_COST_UNREPORTED, LINE_AMENDED, LINE_WITHDRAWN */);
public sealed record AcquiringFeedBatch(AcquiringFeedBatchId Id, InstitutionConnectionId Connection, DateOnly BusinessDate, string FileId, int FileVersion, bool Simulated, IReadOnlyList<AcquiringFeedLine> Lines, DateTimeOffset ImportedAt, IReadOnlyList<AcquiringFeedLineOutcome>? Outcomes = null);
public static class AcquiringFeedPurposes { public const string Feed = "acquiring.feed"; public const string SimulatedPrefix = "SIMULATED-"; public static string FileName(DateOnly d) => $"acquiring-{d:yyyyMMdd}.json"; }

// LedgerTM.Contracts/Accounts/AccountId.cs — changed: ForMerchantSettlement(MerchantAgreementId, CurrencyId) → "merchant-settlement-{agreement}-{ccy}", as ForDisbursement composes
// LedgerTM.Contracts/Pricing/PriceLists/GetPriceListReferenceQuery.cs — changed: PriceListReference(Id, Description, CurrencyId Currency)
// LedgerTM.Contracts/Payments/ISettlementDateResolver.cs — changed (D4)
Task<DateOnly> AddBusinessDays(ExternalAccountId? externalAccountId, DateOnly from, int days, SettlementDirection direction, CancellationToken ct = default);   // a default member that throws; SettlementDateResolver implements it. The rail the account's standard selects for the direction; its calendar through IScheduler.AddBusinessDays; no rail → the tenant's default calendar

// LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs — new and changed (D3, D4, D5)
// LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.cs, not Contracts (only Accounts reads it):
public enum HoldBasis { Amount, NetCredited }   // the dispatcher's claim: the command's amount (debit order, unchanged) or the net credited to Current, floored at 0 (merchant sale)
[PermissionKey("accounts.process-merchant-sale")]
public record ProcessMerchantSaleCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount /* settlement amount */, DateOnly TradingDate /* the run date */, DateOnly ValueDate /* the line's transaction date */,
    string SourceRef, decimal ReportedInterchange, decimal ReportedSchemeFee, DateOnly? HoldReleaseOn, IReadOnlyDictionary<string, string>? PricingAttributes = null) : ISystemCommand;   // dispatched with HoldBasis.NetCredited
[PermissionKey("accounts.process-merchant-refund")]
public record ProcessMerchantRefundCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount, DateOnly TradingDate, DateOnly ValueDate, string SourceRef,
    decimal ReportedInterchange, decimal ReportedSchemeFee, IReadOnlyDictionary<string, string>? PricingAttributes = null) : ISystemCommand;   // no hold, no availability guard
[PermissionKey("accounts.process-merchant-payout")]
public record ProcessMerchantPayoutCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount, DateOnly TradingDate, DateOnly ValueDate, string SourceRef /* the agreement id */, ExternalAccountId ExternalAccount) : ISystemCommand;   // the standing-order shape; seeds $settlementExternalAccount
// Ids: a line TransactionId from Uuid5(connection, processorReference), as ADR-836's; a payout For($"{account.IdPart()}-payout-{tradingDate:yyyy-MM-dd}").
// The dispatcher (bite 2): HoldBasis.NetCredited → after the workflow, an uncleared-funds claim on Current for max(0, Current after − Current before); HoldBasis.Amount → the amount, as today. None when HoldReleaseOn is null or the basis is 0.
// The sale and payout handlers need the dispatcher's price provider and value-date binding (ADR-839 F5) and its back-valued posting (ADR-836).

// LedgerTM.Acquiring/Domain/MerchantAgreement.cs — new (D1)
public sealed class MerchantAgreement : EventSourcedAggregate
{
    public void Open(CounterpartyId merchant, OperatingEntityId operatingEntity, MerchantCategoryCode category, IReadOnlyList<MerchantIdentifier> identifiers, MerchantAgreementTerms terms, DateOnly from, UserId by);
    public void AddSettlementCurrency(MerchantSettlementAccountRef account, DateOnly on);
    public void AmendTerms(MerchantAgreementTerms terms, DateOnly effectiveFrom, UserId by);   // effectiveFrom >= the trading date
    public void AmendPayoutAccount(CurrencyId currency, ExternalAccountId payoutAccount, UserId by, DateOnly on);
    public void Suspend(string reason, UserId by, DateOnly on);  public void Resume(UserId by, DateOnly on);
    public void Terminate(string reason, UserId by, DateOnly on);
    public void Close(DateOnly on);                         // no earlier than TerminatedOn + AcquiringSettings.ClosureTailDays (120)
    public MerchantAgreementTerms TermsOn(DateOnly date);   // a date before From reads the first terms
    // Refusals: MERCHANT_AGREEMENT_NOT_ACTIVE, MERCHANT_AGREEMENT_NOT_SUSPENDED, MERCHANT_AGREEMENT_TERMINATED, MERCHANT_AGREEMENT_TERMS_INVALID, MERCHANT_AGREEMENT_TERMS_BACK_DATED, MERCHANT_AGREEMENT_CURRENCY_HELD
}
// Events ([MessageIdentity("acquiring.merchant-agreement-…")]): MerchantAgreementOpened(Id, Merchant, OperatingEntity, Category, Identifiers, Terms, From, By, On), MerchantSettlementCurrencyAdded(Id, Currency, Account, PayoutAccount, On),
//   MerchantAgreementTermsAmended(Id, Terms, EffectiveFrom, By, On), MerchantPayoutAccountAmended(Id, Currency, PayoutAccount, By, On), MerchantAgreementSuspended, MerchantAgreementResumed, MerchantAgreementTerminated(Id, Reason, By, On), MerchantAgreementClosed(Id, On).
public sealed class MerchantIdentifierReservation { string Id /* "{connection}|{identifier}" */; MerchantAgreementId Agreement; }   // session.Insert in the open's transaction (DocumentAlreadyExistsException → MERCHANT_IDENTIFIER_IN_USE, per the Marten docs); deleted in the close's transaction
public sealed class MerchantIdentifierHistory { string Id /* "{connection}|{identifier}" */; List<(MerchantAgreementId Agreement, DateOnly From, DateOnly? ClosedOn)> Holders; }   // the post step routes a line by its transaction date; a date in a closed holder's window → AGREEMENT_CLOSED

// LedgerTM.Acquiring/Application/Agreements/… — new (D1, D7)
[PermissionKey("acquiring.open-merchant-agreement")] public record OpenMerchantAgreementCommand(MerchantAgreementId Id, CounterpartyId Merchant, OperatingEntityId OperatingEntity, MerchantCategoryCode Category,
    IReadOnlyList<MerchantIdentifier> Identifiers, MerchantAgreementTerms Terms, IReadOnlyList<MerchantSettlementCurrency> SettlementCurrencies, DateOnly From) : ICommand, ICreatesItsTarget { Target "MerchantAgreement" }
//   Handler: MERCHANT_UNKNOWN (no standing), MERCHANT_ROLE_REQUIRED, MERCHANT_NOT_CLEARED (IClearanceStatusProvider.StandingForAsync: not cleared under an active regime, or frozen), MERCHANT_AGREEMENT_EXISTS, CONNECTION_UNKNOWN;
//   per currency: PRICE_LIST_UNKNOWN / PRICE_LIST_CURRENCY_MISMATCH (GetPriceListReferenceQuery), PAYOUT_ACCOUNT_NOT_MERCHANTS (owner ≠ merchant), PAYOUT_ACCOUNT_CURRENCY_MISMATCH, PAYOUT_ACCOUNT_STANDARD_UNSUPPORTED (not an account-number standard);
//   then, first, per currency ProvisionAccountCommand(AccountId.ForMerchantSettlement(Id, ccy), MerchantSettlementAccount, OperatingEntity, ccy, From, PostingGroupId = IPostingGroupReferenceProvider default for the type,
//     ServicingCounterparty = Merchant, Properties { priceList = the list }) via InvokeForTenantAsync (idempotent on the derived id); then Open, AddSettlementCurrency per account, and the reservations, in one transaction.
[PermissionKey("acquiring.add-merchant-settlement-currency")] public record AddMerchantSettlementCurrencyCommand(MerchantAgreementId Id, MerchantSettlementCurrency Currency) : ICommand { … }   // the same checks and provisioning
[PermissionKey("acquiring.amend-merchant-agreement-terms")] public record AmendMerchantAgreementTermsCommand(MerchantAgreementId Id, MerchantAgreementTerms Terms, DateOnly EffectiveFrom) : ICommand { … }
[PermissionKey("acquiring.amend-merchant-payout-account")] public record AmendMerchantPayoutAccountCommand(MerchantAgreementId Id, CurrencyId Currency, ExternalAccountId PayoutAccount) : ICommand { … }   // the same payout-account checks
[PermissionKey("acquiring.suspend-merchant-agreement")] SuspendMerchantAgreementCommand(MerchantAgreementId Id, string Reason); [PermissionKey("acquiring.resume-merchant-agreement")] ResumeMerchantAgreementCommand(MerchantAgreementId Id); [PermissionKey("acquiring.terminate-merchant-agreement")] TerminateMerchantAgreementCommand(MerchantAgreementId Id, string Reason) — each : ICommand { Target "MerchantAgreement" }
public sealed class MerchantAgreementApproverViewReader() : DocumentApproverViewReader<MerchantAgreementSummary, MerchantAgreementId>("MerchantAgreement");  public sealed class MerchantAgreementIsItsOwnHolder() : SelfHoldingAggregate("MerchantAgreement");
public sealed class MerchantAgreementSummary { MerchantAgreementId Id; CounterpartyId Merchant; string MerchantName; OperatingEntityId OperatingEntity; MerchantCategoryCode Category; IReadOnlyList<MerchantIdentifier> Identifiers;
    MerchantAgreementTerms Terms /* computed at read time for the trading date */; IReadOnlyList<DatedTerms> TermsHistory; MerchantAgreementStatus Status; IReadOnlyList<MerchantSettlementAccountRef> SettlementAccounts; DateOnly? NextPayoutOn /* computed at read time */; DateOnly OpenedOn; DateOnly? TerminatedOn; DateOnly? ClosedOn }
//   balances, debt, last and next payout are the accounts' reads, joined by the viewer
public sealed class AcquiringSettings : Settings { public int ClosureTailDays { get; set; } = 120; }   // ADR-843 adds the dispute warning days and group; AmendAcquiringSettingsCommand : ISettingsCommand<AcquiringSettings>, POST /api/settings/acquiring
[PermissionKey("acquiring.view-merchant-agreement")] GetMerchantAgreementQuery(MerchantAgreementId Id) : IQuery<MerchantAgreementSummary?>;  [PermissionKey("acquiring.list-merchant-agreements")] ListMerchantAgreementsQuery(MerchantAgreementStatus? Status) : IQuery<IReadOnlyList<MerchantAgreementSummary>>
// Routes: POST /api/merchant-agreements, POST /api/merchant-agreements/{id}/{add-currency|amend-terms|amend-payout-account|suspend|resume|terminate}, GET /api/merchant-agreements, GET /api/merchant-agreements/{id}. Feature key cards.acquiring on every endpoint, step and page.

// LedgerTM.Acquiring/Application/Feed/… and DayEnd/… — new (D2, D3)
public interface IAcquiringFeedMapper { AcquiringProcessorKind Kind { get; } AcquiringFeedBatch Map(InboundFileDescriptor file, InstitutionConnectionId connection, Stream content); }
// Steps (PreIncrement, NonCritical, FeatureKey "cards.acquiring"): "acquiring.simulate-feed" 51 (RequiresSimulation; writes only when no file exists for the date; business days only), "acquiring.fetch-feed" 52, "acquiring.import-feed" 53,
//   "acquiring.post-feed" 54 — lists every batch with an unposted, non-terminal line and dispatches [PermissionKey("acquiring.post-feed-batch")] PostAcquiringFeedBatchCommand(TenantId, AcquiringFeedBatchId, DateOnly RunDate) : ICommand, ISystemCommand per batch via InvokeForTenantAsync, as ADR-836's PostCardClearingBatchCommand.
// Per line: MerchantIdentifierHistory by the line's transaction date (no holder → UNKNOWN_MERCHANT; a closed holder's window → AGREEMENT_CLOSED, terminal); Sale → ProcessMerchantSaleCommand to the account for SettlementCurrency (none → NO_SETTLEMENT_ACCOUNT_FOR_CURRENCY)
//   for SettlementAmount, TradingDate = RunDate, ValueDate = TransactionDate, the bag (pricing-model = TermsOn(TransactionDate).PricingModel), the reported costs (null → 0; both null → SCHEME_COST_UNREPORTED),
//   HoldReleaseOn = delay(TermsOn(BusinessDate)) == 0 ? null : AddBusinessDays(that currency's PayoutAccount, BusinessDate, delay, Out); Refund → ProcessMerchantRefundCommand; Chargeback/ChargebackReversal → CHARGEBACK_NOT_HANDLED; Adjustment → ADJUSTMENT_NOT_HANDLED;
//   an Accounts DomainException records its code and is retried next run; a re-import merges by reference (LINE_AMENDED, LINE_WITHDRAWN). The dispatcher skips a posted id.
[PermissionKey("acquiring.list-feed-batches")] ListAcquiringFeedBatchesQuery(DateOnly? From, DateOnly? To, MerchantAgreementId? Agreement)   // GET /api/acquiring/feed-batches?from=&to=&agreement=; GET /api/acquiring/feed-batches/{id}
// : IQuery<IReadOnlyList<AcquiringFeedBatch>>;  [PermissionKey("acquiring.view-feed-batch")] GetAcquiringFeedBatchQuery(AcquiringFeedBatchId Id) : IQuery<AcquiringFeedBatch?>
internal static class AcquiringPricingAttributes { public static IReadOnlyDictionary<string, string> For(AcquiringFeedLine line, MerchantAgreementTerms terms, MerchantCategoryCode category); }
// pricing-model, scheme (lower-case), card-product, interchange-region, channel, entry-mode (ADR-841's spellings), currency-conversion (line.Currency != line.SettlementCurrency → yes), dcc, merchant-category (four digits)

// LedgerTM.Acquiring/Application/DayEnd/MerchantPayoutStep.cs — new (D5)
public sealed class MerchantPayoutStep(IMessageBus bus) : IDayEndStep   // "acquiring.payout-merchants", 55, PostIncrement, NonCritical, no feature key (F-1803: run-down outlives the switch); date = ctx.TradingDate.AddDays(1) (F8)
// Lists the agreements due and dispatches [PermissionKey("acquiring.payout-merchant")] PayoutMerchantCommand(TenantId, MerchantAgreementId, DateOnly Date) : ICommand, ISystemCommand per agreement via InvokeForTenantAsync.
// Due: a business day of the payout rail's calendar (ISettlementDateResolver.EarliestSettlementDate(account, d, Out) == d); Active with frequency due (Daily; Weekly the first business day of the ISO week; Monthly the first business day of the month); every Terminated agreement.
// Per settlement account: a = IAccountAvailabilityReader.AvailableAsync(account, date) (null → not active, skipped); Active: a.Available > 0 && >= TermsOn(date).PayoutMinimum → ProcessMerchantPayoutCommand(a.Available, ValueDate = NextSettlementDate(payoutAccount, date, Out, amount), ExternalAccount = payoutAccount);
//   Terminated: a.Claims == 0 && a.Available > 0 → the same, no minimum; every account with Ledger == 0 and Claims == 0, and date >= TerminatedOn + ClosureTailDays → Close.
[PermissionKey("acquiring.close-merchant-agreement")] public record CloseMerchantAgreementCommand(TenantId Tenant, MerchantAgreementId Agreement, DateOnly Date) : ICommand, ISystemCommand;   // the close is its own command, dispatched by the step

// Configuration (D3, D4, D5) — AccountTypesSettings.yaml, MerchantSettlementAccount (Liability, no accruals, no statement schedule, numberingScheme merchant-settlement, property priceList of kind PriceListReference,
//   accountRoles [{ roleType: merchant, owning, min 1, max 1, servicing: true }]): position Current; transactionTypes MerchantSale (Cr Current), MerchantRefund (Dr Current), the merchant charges (Dr Current), the scheme cost rows (GL only), MerchantPayout (Dr Current)
//   operations (each systemOnly — the feed and the payout step are their only callers): acquiring-sale (inputs amount, reportedInterchange, reportedSchemeFee): MerchantSale $amount; each charge fee(type, valueDate, $amount) under > 0; SchemeInterchangeCost $reportedInterchange, SchemeFeeCost $reportedSchemeFee under > 0
//               acquiring-refund: MerchantRefund $amount; RefundFeeCharged fee('refund-fee', valueDate, $amount) under > 0; SchemeInterchangeCostReturned $reportedInterchange, SchemeFeeCostReturned $reportedSchemeFee under > 0
//               merchant-payout: guard Current >= $amount (the guard context reads available); MerchantPayout $amount with settlementExternalAccount: $settlementExternalAccount, paymentInstruction DirectCredit
//   externalIntegrations: acquiringSale, acquiringRefund, merchantPayout; NumberingSettings.yaml: merchant-settlement; AccountRoleTypesSettings.yaml: merchant (owning)
// packages/retail-bank/PriceSettings.yaml: the price types (selectors pricing-model, scheme, card-product, interchange-region, channel); countries/za/retail-bank/PriceSettings.yaml: one rand and one euro acquiring list, each:
//   interchange {} 0, { pricing-model: interchange-plus-plus } 0.002, { pricing-model: interchange-plus-plus, scheme: visa, card-product: consumer-credit, interchange-region: domestic } 0.003, { pricing-model: interchange-plus-plus, card-product: commercial } 0.015;
//   scheme-fee {} 0, { pricing-model: interchange-plus-plus } 0.0005; scheme-fee-per-item {} 0, { pricing-model: interchange-plus-plus } 0.06; acquirer-margin {} 0.005, { pricing-model: blended } 0.0091; acquirer-fee-per-item {} 0.10; refund-fee {} 0.10
// PostingSettings.yaml: Scheme settlement receivable (asset), Merchant payable (liability), Acquiring fee income (income), Acquiring cost of sales (expense); legs as D4

Bites

Bite Description Acceptance criterion Status
1 The project, the contracts, the agreement aggregate and its verbs, the settlement accounts provisioned, the package rows, the feature key, AddBusinessDays, the reads an agreement opens with its settlement account and prices; a merchant without the role is refused; terms amend dated Done
2 The feed, pricing and posting: the batch, the mapper seam, the simulator, the four steps with the re-scan, the sale and refund commands with the bag and the hold, the dispatcher’s net claim, the two workflows a day’s feed is imported and posted, and a line naming no agreement is an exception; a sale is priced interchange++ on receipt and held until T+2; a blended merchant is charged the blended rate; a refund returns the gross and charges the refund fee Done
3 Payout: the step, ProcessMerchantPayoutCommand, the merchant-payout workflow, suspend, terminate, balance owing and close a merchant is paid its available balance on its day by rail; a suspended agreement is not paid; a terminated one is paid out and closed Done
4 The screens, the sample merchant, the probe, the guide articles, the register row an operator opens an agreement and follows a day’s feed to the payout Done

Scenarios

Feature: a merchant's card sales are priced on receipt, held to T+n and paid by rail

# Bite 1
Scenario: an agreement opens with its settlement account and prices
  Given a cleared company holding the merchant role, a captured rand payout account, and the acquiring price lists
  When a clerk opens an interchange++ agreement for it over HTTP with a two-day delay, daily payout above 50 and a rand settlement currency, and later adds a euro settlement currency
  Then the agreement is active, its rand and euro settlement accounts are open and active, owned by the merchant, on their acquiring lists, and its terms read back
  And a price list in another currency, a payout account owned by someone else or in another currency, and an identifier another open agreement carries are each refused
  # Seen at: route:/merchant-agreements/{id}

# Bite 1
Scenario: a merchant without the role is refused
  Given a company without the merchant role
  When a clerk opens an agreement for it
  Then the agreement is refused naming the role, and no account is opened
  # Seen at: route:/merchant-agreements/{id}

# Bite 1
Scenario: terms amend dated
  Given an active agreement with a two-day delay, interchange++
  When it is amended to blended with a three-day delay from the 10th
  Then the terms read two days and interchange++ on the 9th and three days and blended on the 10th, and an amendment dated before the trading date is refused
  # Seen at: route:/merchant-agreements/{id}

# Bite 2
Scenario: a day's feed is imported and posted, and a line naming no agreement is an exception
  Given an active agreement and the processor's feed for the day with two sales and one line for an unknown merchant
  When day-end runs
  Then the two sales are posted to the settlement account and the batch records one exception naming the identifier
  And re-importing the same day posts nothing twice, and once an agreement carrying the identifier is opened the next day-end posts the excepted line
  # Seen at: panel:acquiringFeedBatches

# Bite 2
Scenario: a sale is priced interchange++ on receipt and held until T+2
  Given the worked example's agreement and price rows
  When a 100.00 rand Visa consumer-credit domestic e-commerce sale made on Saturday is received on Monday, reporting interchange 0.30 and scheme fee 0.11
  Then the account is credited 100.00 value-dated Saturday and charged interchange 0.30, scheme fee 0.05, scheme item fee 0.06, margin 0.50 and item fee 0.10, each posting carrying the sale's pricing attributes, and the scheme's cost rows of 0.30 and 0.11 stand on the account's transactions
  And 98.99, less the charges' VAT, is held until Wednesday's walk, when it becomes available, and a 40.00 refund on Tuesday leaves nothing to pay until then
  And a sale whose charges equal or exceed it is held for nothing, and a sale under a zero-day delay is available at once
  # Seen at: route:/accounts/{id}

# Bite 2
Scenario: a blended merchant is charged the blended rate
  Given the same sale on an agreement whose terms are blended
  When it is received
  Then the account is charged margin 0.91 and item fee 0.10 and nothing as interchange or scheme fee, and the scheme's cost rows of 0.30 and 0.11 still stand
  # Seen at: route:/accounts/{id}

# Bite 2
Scenario: a refund returns the gross and charges the refund fee
  Given a posted sale of 100.00
  When a 40.00 refund is received reporting returned interchange of 0.12
  Then the account is debited 40.00 and charged the refund fee of 0.10, no merchant charge is returned, and the returned interchange reduces the scheme's cost
  # Seen at: route:/accounts/{id}

# Bite 3
Scenario: a merchant is paid its available balance on its day by rail
  Given an agreement paying daily at or above 50 with 58.89, less the charges' VAT, available after Wednesday's walk and a captured rand account-number payout account
  When the payout step opens Thursday
  Then an instruction of the whole available is raised to the payout account, value-dated Friday, and the payout posts when it settles
  And a balance below the minimum is carried, a balance equal to it is paid, and a nothing-available account is not paid
  # Seen at: route:/accounts/{id}

# Bite 3
Scenario: a suspended agreement is not paid
  Given a suspended agreement with funds available
  When the payout step runs
  Then nothing is instructed, the feed still posts its sales, and its claims keep releasing
  And once resumed it is paid on its next due day
  # Seen at: route:/merchant-agreements/{id}

# Bite 3
Scenario: a terminated one is paid out and closed
  Given an agreement terminated on Monday with 30.00 below its minimum, held until Wednesday
  When day-end runs until the payout settles
  Then the 30.00 is paid out the day after the release whatever the minimum, and the agreement reads closed once the account stands at zero with nothing outstanding and the closure tail has passed
  And a terminated agreement whose account the merchant owes on stays terminated, and a later line dated within its window is a terminal agreement-closed outcome once it has closed
  # Seen at: route:/merchant-agreements/{id}

# Bite 4
Scenario: an operator opens an agreement and follows a day's feed to the payout
  Given the sample merchant
  When an operator opens its agreement, the day's batch and its settlement account
  Then the agreement shows its terms and payout account, the batch its lines and outcomes, and the account the sale, its fees, the hold and the payout
  # Seen at: route:/merchant-agreements/{id}

Scenario → test

Scenario Bite Project Class Method Probe
an agreement opens with its settlement account and prices 1 LedgerTM.Tests.Component MerchantAgreementTests an_agreement_opens_with_its_settlement_account_and_prices adr-842-server-probe.ts
a merchant without the role is refused 1 LedgerTM.Tests.Component MerchantAgreementTests a_merchant_without_the_role_is_refused — refusal
terms amend dated 1 LedgerTM.Tests.Component MerchantAgreementTests terms_amend_dated —
a day’s feed is imported and posted, and a line naming no agreement is an exception 2 LedgerTM.Tests.Component AcquiringFeedTests a_days_feed_is_imported_and_posted_and_a_line_naming_no_agreement_is_an_exception adr-842-server-probe.ts
a sale is priced interchange++ on receipt and held until T+2 2 LedgerTM.Tests.Component MerchantSettlementPricingTests a_sale_is_priced_interchange_plus_plus_on_receipt_and_held_until_t_plus_2 adr-842-server-probe.ts
a blended merchant is charged the blended rate 2 LedgerTM.Tests.Component MerchantSettlementPricingTests a_blended_merchant_is_charged_the_blended_rate —
a refund returns the gross and charges the refund fee 2 LedgerTM.Tests.Component MerchantSettlementPricingTests a_refund_returns_the_gross_and_charges_the_refund_fee —
a merchant is paid its available balance on its day by rail 3 LedgerTM.Tests.Component MerchantPayoutTests a_merchant_is_paid_its_available_balance_on_its_day_by_rail adr-842-server-probe.ts
a suspended agreement is not paid 3 LedgerTM.Tests.Component MerchantPayoutTests a_suspended_agreement_is_not_paid —
a terminated one is paid out and closed 3 LedgerTM.Tests.Component MerchantPayoutTests a_terminated_one_is_paid_out_and_closed —
an operator opens an agreement and follows a day’s feed to the payout 4 LedgerTM.Tests.Component MerchantAgreementViewerTests the_agreement_the_batch_and_the_account_reads_carry_the_terms_the_lines_the_fees_the_hold_and_the_payout adr-842-server-probe.ts

The net-credited claim is guarded by ExternalSourceClaimTests (unit), which also proves the debit order’s claim unchanged.

UI-surface sweep

Swept src/ui-apps/bank/src for merchant, Merchant, acquiring, MerchantAgreement, AcquiringFeed, settlement-account:

Footprint

Feature projects touched: 10 — LedgerTM.Accounts, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure.Contracts, LedgerTM.Payments, LedgerTM.Pricing, LedgerTM.Seeding.Provisioning, LedgerTM.Seeding.ZaRetail.Samples, LedgerTM.Worker, ui-apps

Contracts types: 56 named, 43 changed by this ADR

Files reading each changed type: 43 types

Domain events touched: 8 — MerchantAgreementClosed, MerchantAgreementOpened, MerchantAgreementResumed, MerchantAgreementSuspended, MerchantAgreementTerminated, MerchantAgreementTermsAmended, MerchantPayoutAccountAmended, MerchantSettlementCurrencyAdded Aggregates touched: 0

Methods at CRAP 30+ in changed files: 4 (unit coverage at main 02e958372)

Warnings

At land: 110 files touched, 95 predicted, 72 unplanned. LedgerTM.Testing.Builders/LedgerTM.Testing.Builders.csproj, LedgerTM.Testing.Infrastructure/LedgerTM.Testing.Infrastructure.csproj, LedgerTM.Testing.Infrastructure/Stubs/AccountsComponentStubs.cs, LedgerTM.Tests.Architecture/LedgerTM.Tests.Architecture.csproj, LedgerTM.Tests.Architecture/Pricing/dated-lookup-allowlist.txt, LedgerTM.Tests.Architecture/TenantSettingsFolderTests.cs, LedgerTM.Tests.Architecture/UnitOfWorkTests.cs, LedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txt, LedgerTM.Tests.Component/Acquiring/AcquiringFeedTestHelper.cs, LedgerTM.Tests.Component/Acquiring/AcquiringSettingsTests.cs, LedgerTM.Tests.Component/Acquiring/BackValuedTaxedSaleTests.cs, LedgerTM.Tests.Component/Acquiring/MerchantSettlementGuardTests.cs, LedgerTM.Tests.Component/Acquiring/MerchantSettlementPricingTests.cs, LedgerTM.Tests.Component/Acquiring/SystemOnlyAcquiringOperationsTests.cs, LedgerTM.Tests.Component/LedgerTM.Tests.Component.csproj, LedgerTM.Tests.Component/Seeding/PackageImporterFolderTests.cs, LedgerTM.Tests.Component/Seeding/SampleMerchantSeedTests.cs, LedgerTM.Tests.Component/Seeding/SeedingComponentFixture.cs, LedgerTM.Tests.Unit/AccessControl/PermissionKeyPinTests.cs, LedgerTM.Tests.Unit/Accounts/AccountTypeIconAndFamilyTests.cs, LedgerTM.Tests.Unit/Acquiring/SimulatorFeedMapperTests.cs, LedgerTM.Tests.Unit/LedgerTM.Tests.Unit.csproj, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Accounts/Application/Commands/RevalueAccount.cs, src/LedgerTM.Accounts/Application/Operations/AccountGuardContextBuilder.cs, src/LedgerTM.Accounts/Application/Operations/OperationInterpreter.cs, src/LedgerTM.Accounts/Domain/Account.Posting.cs, src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.cs, src/LedgerTM.Acquiring/Application/Agreements/AcquiringSettings.cs, src/LedgerTM.Acquiring/Application/Agreements/AddMerchantSettlementCurrency.cs, src/LedgerTM.Acquiring/Application/Agreements/AmendMerchantAgreementTerms.cs, src/LedgerTM.Acquiring/Application/Agreements/AmendMerchantPayoutAccount.cs, src/LedgerTM.Acquiring/Application/Agreements/ListMerchantAgreements.cs, src/LedgerTM.Acquiring/Application/Agreements/MerchantAgreementSummary.cs, src/LedgerTM.Acquiring/Application/Agreements/MerchantAgreements.cs, src/LedgerTM.Acquiring/Application/Agreements/MerchantSettlementChecks.cs, src/LedgerTM.Acquiring/Application/Agreements/ResumeMerchantAgreement.cs, src/LedgerTM.Acquiring/Application/Agreements/SuspendMerchantAgreement.cs, src/LedgerTM.Acquiring/Application/Agreements/TerminateMerchantAgreement.cs, src/LedgerTM.Acquiring/Application/DayEnd/AcquiringFeedCommands.cs, src/LedgerTM.Acquiring/Application/DayEnd/AcquiringFeedPost.cs, src/LedgerTM.Acquiring/Application/Feed/AcquiringFeedConnection.cs, src/LedgerTM.Acquiring/Application/Feed/GetAcquiringFeedBatch.cs, src/LedgerTM.Acquiring/Application/Feed/ListAcquiringFeedBatches.cs, src/LedgerTM.Acquiring/Bootstrapper.cs, src/LedgerTM.Acquiring/Domain/MerchantAgreement.Events.cs, src/LedgerTM.Acquiring/GlobalUsings.cs, src/LedgerTM.Contracts/Accounts/Triggers/TransactionSource.cs, src/LedgerTM.Contracts/Acquiring/AcquiringFeed.cs, src/LedgerTM.Infrastructure.Contracts/Features/FeatureCatalog.cs, src/LedgerTM.Seeding.Provisioning/LedgerTM.Seeding.Provisioning.csproj, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/AccountRoleTypesSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/FeatureSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/InstitutionConnectionSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/NumberingSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/PostingSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/PriceSettings.yaml, src/LedgerTM.Seeding.[redacted].Conversion/LedgerTM.Seeding.[redacted].Conversion.csproj, src/LedgerTM.Seeding.[redacted].Samples/LedgerTM.Seeding.[redacted].Samples.csproj, src/LedgerTM.Seeding.ZaRetail.Samples/Bootstrapper.cs, src/LedgerTM.Seeding.ZaRetail.Samples/LedgerTM.Seeding.ZaRetail.Samples.csproj, src/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedVerifiedClearances.cs, src/ui-apps/bank/src/__tests__/features/accounts/generic/__snapshots__/account-panel-rails.characterization.test.ts.snap, src/ui-apps/bank/src/__tests__/features/accounts/tenant-template-icons.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-dialogs.tsx, src/ui-apps/bank/src/features/acquiring/merchant-agreement-viewer.tsx, src/ui-apps/bank/src/features/back-office/back-office-groups.ts, tools/LedgerTM.EventManifestGenerator/LedgerTM.EventManifestGenerator.csproj, tools/LedgerTM.ShapeSnapshot/LedgerTM.ShapeSnapshot.csproj

Land batches

One land, the whole ADR; reseed: true. Bite 1 starts after ADR-841 batch A lands; bites 2–4 after ADR-836 lands too (F5).

Notes

Landing notes