Track payment effects and expected processor settlement

Purpose

The system needs an outstanding record for each financial effect that should reach a processor deposit.

How It Works

Payment processing records its settlement effect with the causing financial change. Rhythm determines the item’s arrival context from timing configuration and its bank calendar. Pending clearing postpones that context until eligibility is established. Repeated observations retain one financial effect. Missing timing configuration stops eligible recording instead of inventing an expected day.

Relationships

Transactions supplies effects, Books supplies timing configuration, outstanding inspection follows them and matching claims them.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Causing financial work and its expected settlement remain recorded together.Repeated observations retain a single effect.Timing identifies eligibility and expected arrival.
Surfaces: job
Preconditions: The causing financial workflow moves money through a configured merchant account.
Intent sources: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: settlement items written by payments, refunds, reversals and disputes)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D4 (build against live payments)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-04, INV-10, INV-20)

Controls

30 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-005 TC-IAM-006 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-005 TC-AVL-001 TC-AVL-004 TC-MON-001 TC-MON-002 TC-MON-004 TC-PI-002 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002

Business Rules

13 rules, 12 to be proved before approval. A rule's product intent is derived from its origin: 13 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	The causing payment, refund or reversal and its settlement item share one transaction, including rollback; settlement recording rejects calls outside a transaction. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-20) proved by `ATS-ACC-REC-005-01`, `TST-ACC-REC-078`	invariant	service	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#leaves no row once the caller’s transaction rolls back; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records the item inside the transaction; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#refuses outside a transaction
`02`must prove Confirmed	An effect key identifies one recorded item: matching retries return it, while reuse for a different amount is rejected. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-10) proved by `ATS-ACC-REC-005-02`, `TST-ACC-REC-047`, `TST-ACC-REC-078`	invariant	service, database	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#refuses the same key for another amount; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#answers the first item with created false; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#leaves one row; services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses a second item with the same source key (INV-10)
`03`must prove Confirmed	Captures, chargeback reversals, reserve releases and fee refunds increase the deposit; refunds, voids, chargebacks, returns, fees and holds reduce it; adjustments allow either nonzero sign. ✓ A refund of -20000 is stored.✗ A refund of +20000 is refused, naming the amount. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-04) proved by `ATS-ACC-REC-005-03`, `TST-ACC-REC-047`, `TST-ACC-REC-085`	invariant	service, database	test services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses a positive refund; services-accounting:modules/reconciliation/tests/unit/rules/item-kinds.spec.js#refuses a negative capture; services-accounting:modules/reconciliation/tests/unit/rules/item-kinds.spec.js#refuses a positive fee; services-accounting:modules/reconciliation/tests/unit/rules/item-kinds.spec.js#refuses a zero adjustment; services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses a negative capture; services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses a zero adjustment
`04`must prove Confirmed	Settlement recording rejects merchant-unit, currency or declared-processor conflicts and cannot reference more than one causing document. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-02) proved by `ATS-ACC-REC-005-04`, `TST-ACC-REC-078`	validation	service, database	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#refuses another processor than the merchant account’s, naming the processor; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#refuses another unit’s merchant account, naming the merchant account; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#refuses another currency than the merchant account’s, naming the currency; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#refuses an item naming two documents; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#writes no row for a refused item
`05`must prove Confirmed	Eligibility is calculated in the workspace’s zone, moving occurrences after a nonmidnight cut-off to the next business day and rolling weekends or holidays forward; the exact cut-off remains eligible that business day. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope); architecture §12.2 approved with §4 proved by `ATS-ACC-REC-005-05`, `ATS-ACC-REC-005-12`, `ATS-ACC-REC-005-14`, `TST-ACC-REC-078`, `TST-ACC-REC-084`	calculation	service	observed services-accounting:modules/reconciliation/services/persistence/settlement-item-recordings.ts:insertSettlementItem
`06`must prove Confirmed	Expected arrival adds the processor’s business-day lead to eligibility, with merchant overrides replacing default lead and cut-off choices. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope) proved by `ATS-ACC-REC-005-05`, `ATS-ACC-REC-005-12`, `ATS-ACC-REC-005-14`, `TST-ACC-REC-078`, `TST-ACC-REC-084`	calculation	service	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#uses the merchant account’s own lead time and cut-off over the processor’s; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture at 11:00 Eastern on Tuesday, eligible that day and expected Thursday, every field answered; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture after the 21:00 cut-off as eligible the next business day; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture exactly at the 21:00 cut-off as eligible that day; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture on Friday after the cut-off as eligible Tuesday, past the Columbus Day holiday; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#counts business days in the merchant account’s own calendar; services-accounting:modules/reconciliation/tests/unit/rules/business-days.spec.js#moves a capture one second after the cut-off to the next business day; services-accounting:modules/reconciliation/tests/unit/rules/business-days.spec.js#is true for Friday 2026-07-03, since a Saturday holiday is not moved
`07`must prove Confirmed	The merchant’s bank calendar excludes weekends and listed holidays, defaults to the Federal Reserve calendar and does not move a holiday that falls on Saturday. proved by `ATS-ACC-REC-005-05`, `ATS-ACC-REC-005-12`, `ATS-ACC-REC-005-14`, `TST-ACC-REC-078`, `TST-ACC-REC-084`	calculation	service, database	test services-accounting:modules/reconciliation/tests/unit/rules/business-days.spec.js#steps from a Friday over the weekend and Columbus Day to Tuesday; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture at 11:00 Eastern on Tuesday, eligible that day and expected Thursday, every field answered; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture after the 21:00 cut-off as eligible the next business day; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture exactly at the 21:00 cut-off as eligible that day; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records a capture on Friday after the cut-off as eligible Tuesday, past the Columbus Day holiday; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#uses the merchant account’s own lead time and cut-off over the processor’s; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#counts business days in the merchant account’s own calendar; services-accounting:modules/reconciliation/tests/unit/rules/business-days.spec.js#moves a capture one second after the cut-off to the next business day; services-accounting:modules/reconciliation/tests/unit/rules/business-days.spec.js#is true for Friday 2026-07-03, since a Saturday holiday is not moved
`08`must prove Confirmed	Pending electronic checks retain no eligibility or expected date until clearing fills both once; repeated clearing leaves the dates unchanged. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope); journey 0602 proved by `ATS-ACC-REC-005-06`, `ATS-ACC-REC-005-13`, `TST-ACC-REC-078`	lifecycle	service	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#marks it eligible that day, expected four business days later past Columbus Day; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records it with no dates; services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#answers a second mark unchanged
`09`must prove Confirmed	Financial identity and occurrence stay fixed, eligibility dates may be filled once, processor references may be completed once without replacement, and deletion requires workspace purge. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-10) proved by `ATS-ACC-REC-005-07`, `TST-ACC-REC-046`, `TST-ACC-REC-047`	invariant	database	observed services-accounting:modules/reconciliation/db/settlement-items.table.ts
`10` Confirmed	Timing-policy changes affect subsequent items without recalculating the dates already assigned to existing items. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; architecture §12.2) proved by `ATS-ACC-REC-005-10`	policy	service	documented services-accounting:docs/reconciliation/architecture.md#12.2 Expected settlement date
`11`must prove Confirmed	Rhythm supplies shared read-only bank holidays and processor timing defaults, bounding lead and grace values at thirty business days. proved by `ATS-ACC-REC-005-08`, `TST-ACC-REC-030`, `TST-ACC-REC-048`	policy	database	test services-accounting:modules/reconciliation/tests/integration/db/settlement-lead-times.table.integration.spec.js#holds the four seeded lead times, ordered by processor then method, readable by the application role; services-accounting:modules/reconciliation/tests/integration/db/bank-holidays.table.integration.spec.js#holds the Federal Reserve’s 22 holidays of 2026 and 2027 as observed, readable by the application role; services-accounting:modules/reconciliation/tests/integration/db/bank-holidays.table.integration.spec.js#is refused an INSERT (only SELECT is granted); services-accounting:modules/reconciliation/tests/integration/db/settlement-lead-times.table.integration.spec.js#refuses a lead of 31 business days
`12`must prove Confirmed	Manual entry cannot create payment effects such as captures, refunds or chargebacks; those come from the causing financial workflow. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U4) proved by `ATS-ACC-REC-005-09`, `TST-ACC-REC-047`	validation	database	test services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses a manual capture: a person enters fees, reserves and adjustments only
`13`must prove Confirmed	An eligible effect needs an available lead-time and cut-off rule, and recording refuses source keys reserved for manual reconciliation entry. proved by `ATS-ACC-REC-005-11`	validation	service	observed services-accounting:modules/reconciliation/services/settlement-items/settlement-item-recording.ts:recordSettlementItem

Scenarios

Id	Given	When	Then	Provenance
`01`	A Friday-evening Payrix capture follows the cut-off before a Monday bank holiday.	Record the financial effect.	Eligibility and expected arrival fall on the following Tuesday.	test services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 2: expects the refund on its day and the gift, captured after the cut-off, on Tuesday 2026-10-13
`02`	An electronic check awaits clearing.	Record pending money and later mark clearing.	Dates remain absent until clearing assigns arrival four business days later.	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records it with no dates

Edge Cases

Id	Given	When	Then	Provenance
`03`	One capture effect has already been recorded.	Observe it again with the same effect key.	The original item returns without another row.	test services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#leaves one row

Planning

Implementation

Track payment effects and expected processor settlement ​

Purpose ​

How It Works ​

Relationships ​