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

Findings for the ADR

Files touched

Bite 1 — the feature project, the contract types, the seams, the capability move, the no-PAN test

Bite 2 — the facet, its command, validator and read, the page’s settings panel, the seed of the simulation facet

Bite 3 — the authorisation door

Bite 4 — the reversal door and the token provisioning door

Bite 5 — ICardProcessor, the Paymentology adapter, the simulator’s outbound and inbound halves

Bite 6 — the clearing fetch, the import, the batch, the simulator’s file

Bite 7 — the receipts query and the two panels

Prior art

Re-run over ## Contracts after the plan grill. Beyond the ADR’s table:

Declared Search returned Verdict
IInboundMapper, PaymentologyInboundMapper, IClearingFileMapper IStatementParser (BankStatements-internal), FormatProfile (ADR-094) genuinely new — the processor’s shapes into ours, inside Cards; a parser seam would cross the dependency rule
CardProcessorClient, StubCardProcessor StubResolveHttpClientFactory (gateway tests), the feed-delivery stubs reuse the pattern — a per-tenant resolution by kind, and a test double the shared host can point one tenant at
SeedSimulationCardProcessor SeedSimulationPrincipal (ADR-821), SeedDevMember reuse the pattern — a simulation-phase step, idempotent
CardsComponentContext, ClientForConnection, ScriptedDeciders ShippedHostContext.ClientAs, TestConnectionFacet (ADR-821) reuse the pattern — a context per feature, a client per identity kind, a per-tenant test double
SimulateCardClearingStep SimulateExchangeRateDeliveryStep (ADR-767), SimulateChannelReturns (ADR-727) reuse the pattern — RequiresSimulation, writes a real file, the fetch step skips it
CardAuthorisationOutcome, CardClearingPurposes, CardCredentialKind, CardExpiry, CardProcessorKind, CardReissueKind, DecideCardAuthorisationCommand, DecideCardTokenProvisioningCommand, GetCardProcessorQuery, ListCardClearingBatchesQuery, ListCardProcessorReceiptsQuery, ReverseCardAuthorisationCommand, SimulateCardAuthorisationCommand, SimulateCardAuthorisationReversalCommand, SimulateCardCreationCommand, SimulateCardTokenProvisioningCommand Re-run in the lane after bite 4: each hit is this ADR’s own sibling (CardReceiptOutcome, CardClearingItem, CardExpiryJsonConverter, ICardProcessor and the like), laid down by bite 1 genuinely new — no candidate outside the cards family; the search finds the family because it now exists
CardCreationRequest CardAuthorisationRequest, CardTokenProvisioningRequest — this ADR’s own siblings genuinely new — what ICardProcessor is asked to create; the siblings are inbound questions, this is an outbound instruction
MerchantCategoryCodeJsonConverter, CardExpiryJsonConverter StrongIdJsonConverterFactory, OptionEntryJsonConverter reuse the pattern — a per-type JsonConverter beside its value; the strong-id factory covers ids only, and a merchant category code and an expiry are values, not ids

Interfaces

// src/LedgerTM.Contracts/Cards/CardIds.cs — all name-derived (StrongId.UrnFor), one shape
public readonly record struct CardAuthorisationId(string Value) : IStrongId<CardAuthorisationId>
{ public override string ToString() => Value; public static CardAuthorisationId FromReference(string r) => new(StrongId.UrnFor<CardAuthorisationId>(r)); }
public readonly record struct CardReversalId(string Value) : IStrongId<CardReversalId> { /* same */ }
public readonly record struct CardTokenProvisioningId(string Value) : IStrongId<CardTokenProvisioningId> { /* same */ }
public readonly record struct CardTokenReference(string Value) : IStrongId<CardTokenReference> { /* same */ }
public readonly record struct CardClearingBatchId(string Value) : IStrongId<CardClearingBatchId>
{ public static CardClearingBatchId For(InstitutionConnectionId connection, DateOnly businessDate); }

// src/LedgerTM.Contracts/Cards/MerchantCategoryCode.cs — ISO 18245; JSON "7011"
[JsonConverter(typeof(MerchantCategoryCodeJsonConverter))]
public readonly record struct MerchantCategoryCode(string Value) { public static MerchantCategoryCode Parse(string fourDigits); }

// src/LedgerTM.Contracts/Cards/CardCredential.cs
[JsonConverter(typeof(CardExpiryJsonConverter))]   // "2029-09"
public readonly record struct CardExpiry(int Year, int Month);
public enum CardCredentialKind { Plastic, Virtual, DeviceToken }
public enum CardReissueKind { SameNumberNewExpiry, NewNumber }
public enum CardStatus { Ordered, Active, Suspended, LostOrStolen, Closed }
public enum CardChannel { CardPresent, Ecommerce, MailOrTelephone, Recurring, Atm, Wallet }
public enum CardEntryMode { Chip, Contactless, MagneticStripe, Keyed, Token, Unknown }
public sealed record CardControls(bool OnlineAllowed, bool AbroadAllowed, bool AtmAllowed, bool ContactlessAllowed, decimal? PerTransactionCeiling);
// Bin is six or eight digits, LastFour four; no member may hold a PAN (NoPrimaryAccountNumberTests).
public sealed record CardCredential(CardTokenReference Token, string Bin, string LastFour, CardExpiry Expiry, CardCredentialKind Kind);

// src/LedgerTM.Contracts/Cards/CardAuthorisation.cs
public enum CardAuthorisationOutcome { Approved, PartiallyApproved, Declined }
public enum CardDeclineReason { IssuerNotReady, CardNotActive, ControlBreached, InsufficientFunds, NoFundingAccount, DecisionFailed }
public sealed record CardAuthorisationRequest(
    CardAuthorisationId Id, string ProcessorReference, CardTokenReference Token,
    decimal BillingAmount, CurrencyId BillingCurrency, decimal OriginalAmount, CurrencyId OriginalCurrency,
    MerchantCategoryCode Mcc, string MerchantName, string MerchantCountry /* ISO 3166 alpha-2 */,
    CardChannel Channel, CardEntryMode EntryMode, bool CardPresent, DateOnly LocalTransactionDate, DateTimeOffset RequestedAt);
public sealed record CardAuthorisationDecision(CardAuthorisationOutcome Outcome, decimal? ApprovedAmount, CardDeclineReason? Reason);
public sealed record CardAuthorisationReversal(CardReversalId Id, string ProcessorReference, CardAuthorisationId Authorisation, decimal? Amount, DateTimeOffset ReversedAt);

// src/LedgerTM.Contracts/Cards/CardTokenProvisioning.cs
public enum CardTokenProvisioningDecision { Approve, StepUp, Decline }
public sealed record CardTokenProvisioningRequest(
    CardTokenProvisioningId Id, string ProcessorReference, CardTokenReference Token, string WalletProvider, string DeviceDescription, DateTimeOffset RequestedAt);

// src/LedgerTM.Contracts/Cards/CardClearing.cs
public enum CardClearingItemKind { Purchase, Reversal, Refund, Chargeback }
public sealed record CardClearingItem(
    string ProcessorReference, CardAuthorisationId? Authorisation, CardTokenReference Token, CardClearingItemKind Kind,
    decimal FinalAmount, CurrencyId FinalCurrency, decimal OriginalAmount, CurrencyId OriginalCurrency,
    MerchantCategoryCode Mcc, string MerchantName, string MerchantCountry, string? TerminalId,
    CardChannel Channel, CardEntryMode EntryMode, bool Dcc, DateOnly TransactionDate);
// One per connection and business date; rewritten from the same file version on a re-run.
public sealed record CardClearingBatch(
    CardClearingBatchId Id, InstitutionConnectionId Connection, DateOnly BusinessDate,
    string FileId, int FileVersion, bool Simulated, IReadOnlyList<CardClearingItem> Items, DateTimeOffset ImportedAt);
public static class CardClearingPurposes
{
    public const string Clearing = "cards.clearing";
    public const string SimulatedPrefix = "SIMULATED-";
    public static string FileName(DateOnly businessDate, bool simulated);   // [SIMULATED-]cards-clearing-yyyy-MM-dd.csv
}

// src/LedgerTM.Contracts/Cards/CardProcessorKind.cs
public enum CardProcessorKind { None, Paymentology, Simulator }   // None: no processor declared; never resolves a client

// src/LedgerTM.Contracts/Cards/CardReceipts.cs — documents, tenant-scoped, insert-once (Pending → outcome is the one update)
public enum CardReceiptOutcome { Pending, Approved, PartiallyApproved, Declined, NotAnswered, UnknownAuthorisation, StepUp }
public sealed record CardAuthorisationReceipt(
    CardAuthorisationId Id, InstitutionConnectionId Connection, DateOnly TradingDate, CardAuthorisationRequest Request,
    CardReceiptOutcome Outcome, CardDeclineReason? Reason, decimal? ApprovedAmount, DateTimeOffset ReceivedAt, DateTimeOffset? DecidedAt);
public sealed record CardReversalReceipt(
    CardReversalId Id, InstitutionConnectionId Connection, DateOnly TradingDate, CardAuthorisationId Authorisation,
    decimal? Amount, CardReceiptOutcome Outcome /* Approved or UnknownAuthorisation */, DateTimeOffset ReceivedAt);
public sealed record CardTokenProvisioningReceipt(
    CardTokenProvisioningId Id, InstitutionConnectionId Connection, DateOnly TradingDate, CardTokenProvisioningRequest Request,
    CardReceiptOutcome Outcome, CardDeclineReason? Reason /* IssuerNotReady, DecisionFailed */, DateTimeOffset ReceivedAt, DateTimeOffset? DecidedAt);

// src/LedgerTM.Contracts/Cards/ICardProcessor.cs — outbound; resolved per tenant by CardProcessorClient (every caller in the cards projects)
public interface ICardProcessor
{
    Task<CardCredential> CreateCardAsync(CardCreationRequest request, CancellationToken ct = default);
    Task<CardCredential> ReissueAsync(CardTokenReference token, CardReissueKind kind, CancellationToken ct = default);
    Task SetStatusAsync(CardTokenReference token, CardStatus status, CancellationToken ct = default);
    Task SetControlsAsync(CardTokenReference token, CardControls controls, CancellationToken ct = default);
    Task OrderPlasticAsync(CardTokenReference token, CancellationToken ct = default);
    Task CloseAsync(CardTokenReference token, CancellationToken ct = default);
    Task<byte[]?> FetchClearingFileAsync(DateOnly businessDate, CancellationToken ct = default);   // null: not published yet
}
public sealed record CardCreationRequest(CounterpartyId Holder, string EmbossedName, CardCredentialKind Kind, CardControls Controls);

// src/LedgerTM.Contracts/Cards/ICardAuthorisationDecider.cs — returns a decision, writes nothing into the caller's unit of work
public interface ICardAuthorisationDecider { Task<CardAuthorisationDecision> DecideAsync(CardAuthorisationRequest request, CancellationToken ct); }
public interface ICardTokenProvisioningDecider { Task<CardTokenProvisioningDecision> DecideAsync(CardTokenProvisioningRequest request, CancellationToken ct); }

// src/LedgerTM.Infrastructure.Contracts/Capabilities/ICapabilityProvider.cs (moved, F6) — unchanged shape
public interface ICapabilityProvider { Task<bool> IsSimulationEnabledAsync(CancellationToken ct = default); }

// src/LedgerTM.Cards/Domain/CardProcessorSettings.cs — the facet ADR-821 D1 invites
public class CardProcessorSettings : Settings
{
    public InstitutionConnectionId? Connection { get; set; }
    public CardProcessorKind Kind { get; set; }
    public string Environment { get; set; } = "sandbox";
    public string? BaseAddress { get; set; }
    public SecretReference? Credential { get; set; }
    public ExternalAccountId? SettlementAccount { get; set; }
    public OperatingEntityId? OperatingEntity { get; set; }
    public TimeSpan DecisionBudget { get; set; } = TimeSpan.FromSeconds(2);
}

// src/LedgerTM.Cards/Application/Settings/AmendCardProcessor.cs — POST /api/settings/card-processor
[PermissionKey("cards.amend-processor")]
public record AmendCardProcessorCommand(
    InstitutionConnectionId Connection, CardProcessorKind Kind, string Environment, string? BaseAddress,
    SecretReference? Credential, ExternalAccountId SettlementAccount, OperatingEntityId OperatingEntity, TimeSpan DecisionBudget)
    : ISettingsCommand<CardProcessorSettings>;
// Validator refusals, thrown as DomainException so the code survives HTTP: CARD_PROCESSOR_CONNECTION_UNKNOWN,
// CARD_PROCESSOR_TRANSPORT_NOT_PROCESSOR_API, CARD_PROCESSOR_SIMULATOR_NOT_ENABLED, CARD_PROCESSOR_CREDENTIAL_REQUIRED,
// CARD_PROCESSOR_BASE_ADDRESS_REQUIRED, CARD_PROCESSOR_SETTLEMENT_ACCOUNT_REQUIRED, CARD_PROCESSOR_OPERATING_ENTITY_REQUIRED,
// CARD_PROCESSOR_BUDGET_OUT_OF_RANGE (500 ms – 10 s). Removing a connection the facet is attached to is refused by ADR-821's guard.

// src/LedgerTM.Cards/Application/Settings/CardProcessorFacet.cs
public sealed class CardProcessorFacet : IInstitutionConnectionFacet;   // FacetName "card-processor"

// src/LedgerTM.Cards/Application/Queries/GetCardProcessor.cs — GET /api/settings/card-processor
public record CardProcessorView(InstitutionConnectionId? Connection, CardProcessorKind Kind, string Environment, string? BaseAddress,
    bool HasCredential, ExternalAccountId? SettlementAccount, OperatingEntityId? OperatingEntity, TimeSpan DecisionBudget);
[PermissionKey("cards.view-processor")]
public record GetCardProcessorQuery : IQuery<CardProcessorView>;

// src/LedgerTM.Cards/Application/Processor/IInboundMapper.cs — chosen by the connection's kind (F8)
public interface IInboundMapper
{
    CardAuthorisationRequest MapAuthorisation(JsonElement body);
    CardAuthorisationReversal MapReversal(JsonElement body);
    CardTokenProvisioningRequest MapProvisioning(JsonElement body);
}
// src/LedgerTM.Cards/Application/Processor/PaymentologyBodies.cs — the wire shapes the doors bind (F8), JSON camelCase, the
// simulator posts the same shapes. Currency codes are ISO 4217, mapped to CurrencyId by the mapper; channel and entryMode are the enum names; dates ISO 8601.
public sealed record PaymentologyAuthorisationBody(
    string AuthorisationReference, string TokenReference, decimal BillingAmount, string BillingCurrencyCode,
    decimal TransactionAmount, string TransactionCurrencyCode, string MerchantCategoryCode, string MerchantName, string MerchantCountry,
    string Channel, string EntryMode, bool CardPresent, DateOnly LocalTransactionDate, DateTimeOffset RequestedAt);
public sealed record PaymentologyReversalBody(
    string ReversalReference, string AuthorisationReference, decimal? Amount, string? CurrencyCode, DateTimeOffset ReversedAt);
public sealed record PaymentologyProvisioningBody(
    string ProvisioningReference, string TokenReference, string WalletProvider, string DeviceDescription, DateTimeOffset RequestedAt);
// src/LedgerTM.Cards/Application/Processor/PaymentologyInboundMapper.cs — the bodies above into our types.
// Door refusals: a person 403; a token for another connection 403 CARD_PROCESSOR_CONNECTION_MISMATCH; a tenant without
// cards.issuing 403; a missing reference, an unreadable value or a bad MCC 400 and no receipt.

// src/LedgerTM.Cards/Application/Doors/DecideCardAuthorisation.cs — POST /api/cards/authorisations/decide (body: the processor's shape)
[PermissionKey("cards.decide-authorisation")]   // kind ExternallyAuthenticated, bound to cards.issuing
public record DecideCardAuthorisationCommand(CardAuthorisationRequest Request, InstitutionConnectionId Connection)
    : ICommand, IExternallyAuthenticatedCommand, IConnectionScoped
{ public AuthorisationTarget Target => new("CardAuthorisation", Request.Id.Value); }
public sealed record CardDoorReply<T>(bool Answered, T? Decision);   // Answered false ⇒ HTTP 503, no body
// The handler returns CardDoorReply<CardAuthorisationDecision>; the endpoint maps it.

// src/LedgerTM.Cards/Application/Doors/ReverseCardAuthorisation.cs — POST /api/cards/authorisations/reverse
[PermissionKey("cards.reverse-authorisation")]
public record ReverseCardAuthorisationCommand(CardAuthorisationReversal Reversal, InstitutionConnectionId Connection)
    : ICommand, IExternallyAuthenticatedCommand, IConnectionScoped
{ public AuthorisationTarget Target => new("CardReversal", Reversal.Id.Value); }
// Returns the CardReversalReceipt; HTTP 200 always.

// src/LedgerTM.Cards/Application/Doors/DecideCardTokenProvisioning.cs — POST /api/cards/tokens/decide
[PermissionKey("cards.decide-token-provisioning")]
public record DecideCardTokenProvisioningCommand(CardTokenProvisioningRequest Request, InstitutionConnectionId Connection)
    : ICommand, IExternallyAuthenticatedCommand, IConnectionScoped
{ public AuthorisationTarget Target => new("CardTokenProvisioning", Request.Id.Value); }
// Returns CardDoorReply<CardTokenProvisioningDecision>. Decision → receipt: Approve→Approved, StepUp→StepUp, Decline→Declined.

// src/LedgerTM.Cards/Application/Queries/ListCardProcessorReceipts.cs — GET /api/cards/receipts?from=&to= (trading dates)
public enum CardReceiptKind { Authorisation, Reversal, TokenProvisioning }
public sealed record CardProcessorReceiptRow(
    string ProcessorReference, CardReceiptKind Kind, decimal? Amount, CurrencyId? Currency, CardReceiptOutcome Outcome,
    CardDeclineReason? Reason, DateTimeOffset ReceivedAt, InstitutionConnectionId Connection);
[PermissionKey("cards.list-receipts")]
public record ListCardProcessorReceiptsQuery(DateOnly From, DateOnly To) : IQuery<IReadOnlyList<CardProcessorReceiptRow>>;

// src/LedgerTM.Cards/Application/Queries/ListCardClearingBatches.cs — GET /api/cards/clearing?from=&to=
public sealed record CardClearingBatchRow(CardClearingBatchId Id, DateOnly BusinessDate, string FileId, int FileVersion, bool Simulated, int ItemCount, DateTimeOffset ImportedAt);
[PermissionKey("cards.list-clearing")]
public record ListCardClearingBatchesQuery(DateOnly From, DateOnly To) : IQuery<IReadOnlyList<CardClearingBatchRow>>;

// src/LedgerTM.Cards/Application/Processor/IClearingFileMapper.cs — chosen by kind; PaymentologyClearingMapper is the only file naming a column
public interface IClearingFileMapper
{
    IReadOnlyList<CardClearingItem> Read(byte[] file);     // throws CardClearingMappingException naming the row on a bad MCC or kind
    byte[] Write(IReadOnlyList<CardClearingItem> items);   // the simulator's file; Read(Write(x)) == x
}

// src/LedgerTM.Cards/Application/DayEnd — all NonCritical, PreIncrement, constructor takes no tenant-scoped service
public sealed class SimulateCardClearingStep : IDayEndStep   // order 41, RequiresSimulation => true, id "cards.simulate-clearing"
public sealed class FetchCardClearingStep : IDayEndStep      // order 42, id "cards.fetch-clearing"; walks from the day after the last batch, else seven days back, to the run date
public sealed class ImportCardClearingStep : IDayEndStep     // order 43, id "cards.import-clearing"

// src/LedgerTM.Cards/Simulation/SimulateCommands.cs — ISystemCommand, no HTTP route; refused with CARD_SIMULATION_NOT_ENABLED
// unless the tenant's kind is Simulator and ICapabilityProvider says enabled. Each runs the real inbound command in
// IdentityFrame.ForConnection as the tenant's simulation principal (IMachinePrincipalReader.ActorForAsync).
public record SimulateCardCreationCommand(CounterpartyId Holder, string EmbossedName, CardCredentialKind Kind) : ICommand, ISystemCommand
{ public AuthorisationTarget Target => new("CardProcessorSimulation", Holder.Value); }        // returns CardCredential
public record SimulateCardAuthorisationCommand(
    CardTokenReference Token, decimal Amount, CurrencyId Currency, MerchantCategoryCode Mcc, string MerchantName, string MerchantCountry,
    CardChannel Channel, CardEntryMode EntryMode, bool CardPresent, string? ProcessorReference = null) : ICommand, ISystemCommand
{ public AuthorisationTarget Target => new("CardProcessorSimulation", Token.Value); }         // returns the CardAuthorisationId used
public record SimulateCardAuthorisationReversalCommand(CardAuthorisationId Authorisation, decimal? Amount, string? ProcessorReference = null) : ICommand, ISystemCommand
{ public AuthorisationTarget Target => new("CardProcessorSimulation", Authorisation.Value); } // returns the CardReversalId used
public record SimulateCardTokenProvisioningCommand(CardTokenReference Token, string WalletProvider, string Device) : ICommand, ISystemCommand
{ public AuthorisationTarget Target => new("CardProcessorSimulation", Token.Value); }         // returns the CardTokenProvisioningId used

// LedgerTM.Testing.Infrastructure/Cards — the component suites' doubles (F9)
public class CardsComponentContext : ShippedHostContext
{
    public CardsComponentContext(CardsComponentFixture fixture);
    public ExternalAccountId SettlementAccount { get; }
    public OperatingEntityId OperatingEntity { get; }
    // Seeds, for this test's tenant: connection sim-processor (ProcessorApi), the card-processor facet (Simulator, 2 s),
    // simulation enabled, a manifest with cards.issuing, a settlement external account, an operating entity, a simulation principal.
    public HttpClient ClientForConnection();            // a connection token for sim-processor's principal
    public InstitutionConnectionId Connection { get; }
    public ScriptedDeciders Deciders { get; }
    public FakeTimeProvider Clock { get; }              // this tenant's door clock only; the host's TimeProvider is untouched
}
public sealed class ScriptedDeciders : ICardAuthorisationDecider, ICardTokenProvisioningDecider
{
    public void Set(string tenantSlug, Func<CardAuthorisationRequest, CancellationToken, Task<CardAuthorisationDecision>> decide);
    public void Set(string tenantSlug, Func<CardTokenProvisioningRequest, CancellationToken, Task<CardTokenProvisioningDecision>> decide);
    public void Clear(string tenantSlug);               // the door sees no decider for that tenant (IssuerNotReady); the production no-decider path has its own unit test
    public int Calls(string tenantSlug);
    public TaskCompletionSource Gate(string tenantSlug); // a decider awaits it; the test releases it (no Task.Delay)
}
public sealed class StubCardProcessor : ICardProcessor   // kind Paymentology for one tenant; FetchClearingFileAsync answers from a per-date map
{ public void Publish(string tenantSlug, DateOnly businessDate, IReadOnlyList<CardClearingItem> items); }

Bites

Bite Description Acceptance criterion Status
1 The LedgerTM.Cards feature project and its fourteen reference sites; every contract type in LedgerTM.Contracts/Cards; the three seams; ICapabilityProvider moved to Infrastructure.Contracts; the cards.issuing feature key; NoPrimaryAccountNumberTests and CardVocabularyTests A card contract type that carries a primary account number fails the build Pending
2 CardProcessorSettings with its validator, AmendCardProcessorCommand, GetCardProcessorQuery, the facet registration, the two keys, the simulation-phase seed of the facet and settlement account, the page’s settings panel, the component context. Register: ISO 18245, ISO 7812, PCI DSS v4, ISO 8583 rows. Guide: the card processor article A tenant that has bought cards declares its processor as a connection; Kind Simulator is refused where simulation is not enabled Pending
3 The authorisation door: the declared wire body and inbound mapper, the pending receipt in its own unit of work, the decider under the budget’s token on TimeProvider, NotAnswered then 503, IssuerNotReady without a decider, DecisionFailed on a throw; the key into ExternallyAuthenticatedKeys; the scripted deciders An authorisation is decided by the registered decider and answered inside the budget; A repeated authorisation is answered from its receipt; Two identical authorisations in flight reach one decider; A person cannot use the authorisation door; With no decider registered every authorisation is declined as not ready; A decision that misses the budget is refused at once and recorded as not answered Pending
4 The reversal door with its own receipt and UnknownAuthorisation, and the token provisioning door with its own pending receipt and budget; two keys into ExternallyAuthenticatedKeys A merchant reversal reaches the ledger as the connection; A reversal of an authorisation the ledger never saw is accepted and recorded as unknown; A device wallet asks to provision the card and is told to step up, once Pending
5 ICardProcessor, the Paymentology adapter and outbound mapper, CardProcessorClient resolving by kind, the simulator’s outbound half, the four simulate commands with their guards, the stub processor Creating a card through the simulator returns a credential and never a card number Pending
6 The clearing file mapper, SimulateCardClearingStep, the replay-safe fetch and import steps walking calendar days from the day after the last batch, CardClearingBatch, ListCardClearingBatchesQuery The day’s simulated approvals become a clearing batch for that day, written and imported in one run; A processor’s file for a business date is fetched the next morning and keyed by that date; With no batch yet the first run fetches from seven days back Pending
7 ListCardProcessorReceiptsQuery by trading date, the receipts and clearing panels on the card-processor page, and the probe. Guide: the receipts and clearing sections The receipts a tenant answered today are listed beside the clearing batches Pending

Scenarios

Feature: A card processor speaks to the ledger through one seam, and no card number crosses it

# Bite 1
Scenario: A card contract type that carries a primary account number fails the build
  Given the contract types for cards
  When a type on that surface gains a member named for a primary account number, or a sixteen-digit constant that passes the Luhn check
  Then the architecture test fails naming the type and the member
  And a member named Bin or LastFour passes
  # Seen at: none

# Bite 2
Scenario: A tenant that has bought cards declares its processor as a connection
  Given the za-retail tenant licenses cards issuing, simulation is enabled, and its settings hold connection sim-processor with transport ProcessorApi
  When an operator amends the tenant's card processor to kind Simulator with a two-second decision budget, a settlement account and an operating entity
  Then the processor reads back as kind Simulator on connection sim-processor with those values
  And the connection lists the card-processor facet as attached
  And a tenant whose manifest omits cards issuing is refused the processor read and the amend
  # Seen at: route:/connectivity/card-processor

# Bite 2
Scenario: Kind Simulator is refused where simulation is not enabled
  Given a tenant licensing cards issuing whose simulation is not enabled
  When an operator amends the card processor to kind Simulator
  Then the amend is refused naming the kind
  And amending it to kind Paymentology with a base address and a credential is accepted
  # Seen at: route:/connectivity/card-processor

# Bite 3
Scenario: An authorisation is decided by the registered decider and answered inside the budget
  Given the za-retail tenant's processor connection is authenticated as its machine identity
  And a decider is registered that approves 5,000.00 ZAR at merchant category 7011
  When the processor asks to authorise AUTH-1 for 5,000.00 ZAR at merchant category 7011, card present
  Then the reply is Approved
  And a receipt for AUTH-1 records the request, the decision and when it was answered
  # Seen at: panel:cardProcessorReceipts

# Bite 3
Scenario: A repeated authorisation is answered from its receipt
  Given AUTH-1 has been answered Approved
  When the processor asks to authorise AUTH-1 again with the same request
  Then the reply is Approved
  And the decider was not consulted a second time
  # Seen at: panel:cardProcessorReceipts

# Bite 3
Scenario: Two identical authorisations in flight reach one decider
  Given a decider is registered that answers only when the test releases it
  When the processor asks to authorise AUTH-4 twice at once
  Then the decider is consulted once
  And both replies carry the same decision once it is released
  And one receipt exists for AUTH-4
  # Seen at: panel:cardProcessorReceipts

# Bite 3
Scenario: A person cannot use the authorisation door
  Given a tenant administrator of za-retail holding every role
  When they post an authorisation request to the door
  Then the request is refused
  And no receipt is written
  # Seen at: none

# Bite 3
Scenario: With no decider registered every authorisation is declined as not ready
  Given no decider is registered for the tenant
  When the processor asks to authorise AUTH-2
  Then the reply is Declined with reason IssuerNotReady
  And a receipt for AUTH-2 records the decline
  # Seen at: panel:cardProcessorReceipts

# Bite 3
Scenario: A decision that misses the budget is refused at once and recorded as not answered
  Given a decider is registered that answers after three seconds
  And the connection's decision budget is two seconds
  When the processor asks to authorise AUTH-3
  Then at two seconds the reply is a refusal to answer, carrying no decision
  And a receipt for AUTH-3 records outcome NotAnswered before that reply is sent
  And the decider's late answer changes nothing
  And asking to authorise AUTH-3 again is refused to answer again without consulting the decider
  # Seen at: panel:cardProcessorReceipts

# Bite 4
Scenario: A merchant reversal reaches the ledger as the connection
  Given AUTH-1 has been answered Approved
  When the processor reverses AUTH-1 as REV-1
  Then a reversal receipt REV-1 names AUTH-1, the amount, when it arrived and the connection that sent it
  And the authorisation receipt for AUTH-1 is unchanged
  And a second reversal of AUTH-1 is a second reversal receipt
  # Seen at: panel:cardProcessorReceipts

# Bite 4
Scenario: A reversal of an authorisation the ledger never saw is accepted and recorded as unknown
  Given no receipt exists for AUTH-9
  When the processor reverses AUTH-9 as REV-2
  Then the reversal is accepted
  And a reversal receipt REV-2 names AUTH-9 with outcome UnknownAuthorisation
  # Seen at: panel:cardProcessorReceipts

# Bite 4
Scenario: A device wallet asks to provision the card and is told to step up, once
  Given a token provisioning decider is registered that answers StepUp for a first device
  When the processor asks whether the card may be provisioned to a new device, as request PROV-1
  Then the reply is StepUp
  And a provisioning receipt for PROV-1 records the request and the reply
  And asking PROV-1 again is answered from that receipt without consulting the decider
  # Seen at: panel:cardProcessorReceipts

# Bite 5
Scenario: Creating a card through the simulator returns a credential and never a card number
  Given the tenant's processor is the simulator
  When a simulated card is created for a counterparty
  Then the reply is a credential with a token reference, a BIN of six digits, a last four of four digits, an expiry month and kind Plastic
  And no field of the reply, and no field of the simulator's card record, holds more than twelve digits
  And on a tenant whose processor is not the simulator, simulating anything is refused
  # Seen at: none

# Bite 6
Scenario: The day's simulated approvals become a clearing batch for that day, written and imported in one run
  Given the simulator approved AUTH-1 for 5,000.00 ZAR at merchant category 7011 on trading date 29 September 2026
  When day-end runs for 29 September 2026 on the simulation tenant
  Then a clearing file prefixed SIMULATED- exists in the inbound file store for purpose cards.clearing and business date 29 September 2026
  And a clearing batch for connection sim-processor and 29 September 2026 holds one item naming AUTH-1, 5,000.00 ZAR, merchant category 7011 and kind Purchase, marked simulated
  And running day-end for 29 September 2026 again leaves one batch with one item
  # Seen at: route:/connectivity/card-processor

# Bite 6
Scenario: A processor's file for a business date is fetched the next morning and keyed by that date
  Given the tenant's processor is a stubbed processor that is not the simulator
  And it publishes the clearing file for Saturday 26 September 2026, an empty one for Sunday 27 September 2026, and one for Monday 28 September 2026 by the morning of 29 September 2026
  When day-end runs for 29 September 2026
  Then files are received into the inbound file store for 26, 27 and 28 September 2026, the 27th empty
  And a clearing batch exists for each of those dates, the 27th with no items
  # Seen at: route:/connectivity/card-processor

# Bite 7
Scenario: The receipts a tenant answered today are listed beside the clearing batches
  Given AUTH-1 was approved, AUTH-2 was declined as not ready, AUTH-1 was reversed as REV-1 and PROV-1 was answered StepUp on today's trading date
  When an operator opens the card processor page's receipts panel for today's trading date
  Then four rows are listed, newest first, each with its reference, its kind, its amount where it has one, its outcome and its reason
  And the clearing panel lists the batches by business date with their item counts
  # Seen at: panel:cardProcessorReceipts

# Bite 3
Scenario: An authorisation from a token issued to another connection is refused
  Given a second processor connection exists on the tenant with its own machine identity
  When that identity posts an authorisation to the door naming the first connection
  Then the request is refused as a connection mismatch
  And no receipt is written
  # Seen at: none

# Bite 3
Scenario: An authorisation without a processor reference is rejected undecided
  Given the processor connection is authenticated as its machine identity
  When it posts an authorisation body with no reference
  Then the request is rejected as a bad request
  And no receipt is written and the decider is not consulted
  # Seen at: none

# Bite 4
Scenario: A provisioning request with no decider is declined as not ready
  Given no token provisioning decider is registered for the tenant
  When the processor asks whether the card may be provisioned, as request PROV-2
  Then the reply is Decline
  And a provisioning receipt for PROV-2 records the decline with reason IssuerNotReady
  # Seen at: panel:cardProcessorReceipts

# Bite 5
Scenario: Simulation is refused where it is not enabled or not declared
  Given a tenant whose processor kind is Paymentology, and a tenant with no processor declared
  When any of the four simulate commands is dispatched on either tenant
  Then it is refused naming the simulation
  And no receipt and no simulator record is written
  # Seen at: none

# Bite 6
Scenario: With no batch yet the first run fetches from seven days back
  Given a tenant whose processor is a stubbed processor and no clearing batch exists
  When day-end runs for 29 September 2026
  Then files are asked for from 22 September 2026 to 29 September 2026
  And a day the processor has not published is no batch and is asked for again on the next run
  # Seen at: route:/connectivity/card-processor

# Bite 7
Scenario: The receipts window is by trading date, and the processor's identity cannot read it
  Given AUTH-8 arrived after the trading date rolled but before midnight
  When an operator lists receipts for the new trading date
  Then AUTH-8 is listed under the new trading date and not the old one
  And the processor's machine identity is refused the receipts and clearing reads
  # Seen at: panel:cardProcessorReceipts

Scenario → test

Scenario Bite Project Class Method Probe
A card contract type that carries a primary account number fails the build 1 LedgerTM.Tests.Architecture NoPrimaryAccountNumberTests a_pan_shaped_member_or_constant_fails_the_build — build rule, nothing to look at
A tenant that has bought cards declares its processor as a connection 2 LedgerTM.Tests.Component CardProcessorSettingsTests amending_the_processor_reads_back_and_a_tenant_without_the_feature_is_refused adr-820-server-probe.ts
Kind Simulator is refused where simulation is not enabled 2 LedgerTM.Tests.Component CardProcessorSettingsTests kind_simulator_is_refused_without_simulation_enabled — refusal, nothing to look at
An authorisation is decided by the registered decider and answered inside the budget 3 LedgerTM.Tests.Component CardAuthorisationDoorTests an_authorisation_is_decided_and_receipted_inside_the_budget adr-820-server-probe.ts
A repeated authorisation is answered from its receipt 3 LedgerTM.Tests.Component CardAuthorisationDoorTests a_repeated_authorisation_is_answered_from_its_receipt adr-820-server-probe.ts
Two identical authorisations in flight reach one decider 3 LedgerTM.Tests.Component CardAuthorisationDoorTests two_identical_authorisations_in_flight_reach_one_decider — timing, no surface
A person cannot use the authorisation door 3 LedgerTM.Tests.Component CardAuthorisationDoorTests a_person_is_refused_the_door — refusal, nothing to look at
With no decider registered every authorisation is declined as not ready 3 LedgerTM.Tests.Component CardAuthorisationDoorTests without_a_decider_every_authorisation_is_declined_as_not_ready adr-820-server-probe.ts
A decision that misses the budget is refused at once and recorded as not answered 3 LedgerTM.Tests.Component CardAuthorisationDoorTests a_late_decision_is_refused_and_recorded_as_not_answered adr-820-server-probe.ts
A merchant reversal reaches the ledger as the connection 4 LedgerTM.Tests.Component CardReversalDoorTests a_reversal_is_its_own_receipt_from_the_connection adr-820-server-probe.ts
A reversal of an authorisation the ledger never saw is accepted and recorded as unknown 4 LedgerTM.Tests.Component CardReversalDoorTests a_reversal_of_an_unknown_authorisation_is_accepted_and_recorded adr-820-server-probe.ts
A device wallet asks to provision the card and is told to step up, once 4 LedgerTM.Tests.Component CardTokenProvisioningDoorTests a_provisioning_request_is_answered_once_and_receipted adr-820-server-probe.ts
Creating a card through the simulator returns a credential and never a card number 5 LedgerTM.Tests.Component CardProcessorClientTests simulating_a_card_returns_a_credential_with_no_pan_and_is_refused_off_the_simulator — nothing stores the card yet
The day’s simulated approvals become a clearing batch for that day, written and imported in one run 6 LedgerTM.Tests.Component CardClearingTests simulated_approvals_become_a_clearing_batch_and_a_rerun_leaves_one adr-820-server-probe.ts
A processor’s file for a business date is fetched the next morning and keyed by that date 6 LedgerTM.Tests.Component CardClearingTests a_processors_files_are_fetched_for_every_calendar_day_and_keyed_by_business_date — a stubbed processor, no surface
The receipts a tenant answered today are listed beside the clearing batches 7 LedgerTM.Tests.Component CardProcessorReceiptsTests todays_receipts_are_listed_newest_first_beside_the_batches adr-820-server-probe.ts
An authorisation from a token issued to another connection is refused 3 LedgerTM.Tests.Component CardAuthorisationDoorTests a_connection_token_for_another_connection_is_refused — refusal, nothing to look at
An authorisation without a processor reference is rejected undecided 3 LedgerTM.Tests.Component CardAuthorisationDoorTests an_authorisation_without_a_processor_reference_is_rejected_undecided — refusal, nothing to look at
A provisioning request with no decider is declined as not ready 4 LedgerTM.Tests.Component CardTokenProvisioningDoorTests without_a_decider_provisioning_is_declined_and_receipted adr-820-server-probe.ts
Simulation is refused where it is not enabled or not declared 5 LedgerTM.Tests.Component CardProcessorClientTests every_simulate_command_is_refused_where_simulation_is_not_enabled, a_tenant_with_no_card_processor_configured_is_refused_simulation — refusal, nothing to look at
With no batch yet the first run fetches from seven days back 6 LedgerTM.Tests.Component CardClearingTests with_no_batch_yet_the_first_run_fetches_from_seven_days_back, a_file_not_yet_published_is_no_batch_and_is_fetched_on_a_later_run — a stubbed processor, no surface
The receipts window is by trading date, and the processor’s identity cannot read it 7 LedgerTM.Tests.Component CardProcessorReceiptsTests the_receipts_window_is_by_trading_date_not_by_when_they_arrived, the_processors_machine_identity_is_refused_the_receipts_and_clearing_reads adr-820-server-probe.ts

The authors’ remaining methods (pending-before-decided, throwing and nonsense deciders, repeat with a different body, reversal of a declined or unanswered authorisation, the mapper and vocabulary unit tests) are unhappy paths under the scenarios above; they ship with their bite and need no scenario of their own.

UI-surface sweep

Swept src/ui for card-processor, CardProcessor, cards., cardAuthorisation, receipts, clearing, connectivity/: no hits outside generated files (the word cards in staged-change-list.tsx and position-cards.test.ts is the approval-card and position-card sense, unrelated). What this ADR adds to the UI:

No existing UI surface is deleted, renamed or repointed. The three doors have no UI.

Footprint

Feature projects touched: 7 — LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure, LedgerTM.Infrastructure.Contracts, LedgerTM.Seeding, LedgerTM.Seeding.Provisioning, ui

Contracts types: 71 named, 64 changed by this ADR

Files reading each changed type: 64 types

Domain events touched: 0 Aggregates touched: 0

Methods at CRAP 30+ in changed files: 0 (unit coverage at main b9ed61a6c) Permission keys to add: 12 — amend-card-processor, decide-card-authorisation, decide-card-token-provisioning, i-system, reverse-card-authorisation, simulate-card-authorisation, simulate-card-authorisation-reversal, simulate-card-creation, simulate-card-token-provisioning, get-card-processor-query, list-card-clearing-batches-query, list-card-processor-receipts-query

Warnings

At land: 107 files touched, 94 predicted, 52 unplanned. LedgerTM.Testing.Builders/LedgerTM.Testing.Builders.csproj, LedgerTM.Testing.Infrastructure/Cards/CardDoorClocks.cs, LedgerTM.Testing.Infrastructure/LedgerTM.Testing.Infrastructure.csproj, LedgerTM.Testing.Infrastructure/SharedComponentHost.cs, LedgerTM.Tests.Architecture/ContractsSharedSurfaceTests.cs, LedgerTM.Tests.Architecture/LedgerTM.Tests.Architecture.csproj, LedgerTM.Tests.Architecture/PrimaryAccountNumberWalker.cs, LedgerTM.Tests.Architecture/SessionAcquisitionConfinementTests.cs, LedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsv, LedgerTM.Tests.Architecture/StoredShapeOwnershipTests.cs, LedgerTM.Tests.Architecture/TenantSettingsFolderTests.cs, LedgerTM.Tests.Architecture/UnitOfWorkTests.cs, LedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txt, LedgerTM.Tests.Component/Cards/CardTokenProvisioningDoorTests.cs, LedgerTM.Tests.Component/DayEnd/UnservedFeatureRefusalTests.cs, LedgerTM.Tests.Component/LedgerTM.Tests.Component.csproj, LedgerTM.Tests.Component/Payments/Returns/CollectChannelReturnsTests.cs, LedgerTM.Tests.Unit/Infrastructure/Capabilities/CapabilityProviderTests.cs, LedgerTM.Tests.Unit/Infrastructure/DayEnd/DayEndStepRegistryTests.cs, LedgerTM.Tests.Unit/LedgerTM.Tests.Unit.csproj, LedgerTM.Tests.Unit/Operations/DayEndSagaTests.cs, LedgerTM.Tests.Unit/[redacted]/ExportStepPlacementTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Cards/Application/DayEnd/CardClearingCommands.cs, src/LedgerTM.Cards/Application/DayEnd/CardClearingSteps.cs, src/LedgerTM.Cards/Application/Doors/CardDoorClock.cs, src/LedgerTM.Cards/Application/Processor/PaymentologyClearingMapper.cs, src/LedgerTM.Cards/Bootstrapper.cs, src/LedgerTM.Cards/GlobalUsings.cs, src/LedgerTM.Cards/Simulation/SimulatorAuthorisation.cs, src/LedgerTM.Contracts/Cards/ICardAuthorisationDecider.cs, src/LedgerTM.Contracts/Cards/ICardTokenProvisioningDecider.cs, src/LedgerTM.Seeding.Provisioning/LedgerTM.Seeding.Provisioning.csproj, src/LedgerTM.Seeding.Provisioning/PackageExporter.cs, src/LedgerTM.Seeding.Provisioning/PackageImporter.cs, 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/SeedSimulationCardProcessor.cs, src/ui-apps/bank/src/__tests__/standard-table-rowhref-guard.test.ts, src/ui-apps/bank/src/app.tsx, src/ui-apps/bank/src/features/connectivity/card-processor-activity.tsx, src/ui-apps/bank/src/features/connectivity/card-processor-form.tsx, src/ui-apps/bank/src/features/connectivity/card-processor-page.tsx, src/ui-apps/bank/src/features/connectivity/hooks/card-processor.ts, src/ui-apps/bank/src/features/settings/category-taxonomy.ts, src/ui-apps/bank/src/features/settings/settings-class-map.ts, src/ui-apps/bank/src/lib/api.ts, src/ui-apps/bank/ui-review/adr-uat/flows/adr-820-server-probe.ts, tools/LedgerTM.EventManifestGenerator/LedgerTM.EventManifestGenerator.csproj, tools/LedgerTM.ShapeSnapshot/LedgerTM.ShapeSnapshot.csproj

Land batches

One land — the whole ADR. Reseed once at the land (reseed: true: the feature key, the permission keys, the simulation-phase seed). This ADR lands after ADR-821; the card aggregate and the oracle ADRs land after this one, each in its own lane. Those are dependencies between lands, not a reason to split this one.

Notes

Changed during the plan grill

Phase A (the test author’s question pass) and a fresh reader over the signatures, 2026-09-30. The ADR’s own ## Changed during the plan grill carries the decision-level changes; what the plan changed on its own:

Landing notes

(appended by /ltm-partition and by lanes)