--- id: CAP-ACC-REC-005 title: Track payment effects and expected processor settlement feature: FEAT-ACC-REC-04 product_area: accounting module: reconciliation revision: 2 status: draft product_intent: confirmed implementation_evidence: observed supersedes: - react-console acceptance inventory CAP-ACC-REC-003 - react-console acceptance inventory CAP-ACC-REC-026 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 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) purpose: The system needs an outstanding record for each financial effect that should reach a processor deposit. outcomes: - Causing financial work and its expected settlement remain recorded together. - Repeated observations retain a single effect. - Timing identifies eligibility and expected arrival. concepts: - CON-ACC-REC-002 actors: - ACT-ACC-011 surfaces: - job preconditions: - The causing financial workflow moves money through a configured merchant account. postconditions: [] permissions: [] rules: - id: BR-CAP-ACC-REC-005-01 proved_by: [ATS-ACC-REC-005-01, TST-ACC-REC-078] statement: >- The causing payment, refund or reversal and its settlement item share one transaction, including rollback; settlement recording rejects calls outside a transaction. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-20) - id: BR-CAP-ACC-REC-005-02 proved_by: [ATS-ACC-REC-005-02, TST-ACC-REC-047, TST-ACC-REC-078] statement: >- An effect key identifies one recorded item: matching retries return it, while reuse for a different amount is rejected. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- 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) origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-10) - id: BR-CAP-ACC-REC-005-03 proved_by: [ATS-ACC-REC-005-03, TST-ACC-REC-047, TST-ACC-REC-085] statement: >- 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. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- 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 origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-04) examples: positive: A refund of -20000 is stored. negative: 'A refund of +20000 is refused, naming the amount.' - id: BR-CAP-ACC-REC-005-04 proved_by: [ATS-ACC-REC-005-04, TST-ACC-REC-078] statement: >- Settlement recording rejects merchant-unit, currency or declared-processor conflicts and cannot reference more than one causing document. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- 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 origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-02) - id: BR-CAP-ACC-REC-005-05 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] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/settlement-item-recordings.ts:insertSettlementItem 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 - id: BR-CAP-ACC-REC-005-06 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] statement: >- Expected arrival adds the processor’s business-day lead to eligibility, with merchant overrides replacing default lead and cut-off choices. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope) - id: BR-CAP-ACC-REC-005-07 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] statement: >- 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. kind: calculation enforced_at: - service - database must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-ACC-REC-005-08 proved_by: [ATS-ACC-REC-005-06, ATS-ACC-REC-005-13, TST-ACC-REC-078] statement: >- Pending electronic checks retain no eligibility or expected date until clearing fills both once; repeated clearing leaves the dates unchanged. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope); journey 0602 - id: BR-CAP-ACC-REC-005-09 proved_by: [ATS-ACC-REC-005-07, TST-ACC-REC-046, TST-ACC-REC-047] statement: >- 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. kind: invariant enforced_at: - database must_prove: true provenance: observed source: 'services-accounting:modules/reconciliation/db/settlement-items.table.ts' origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-10) - id: BR-CAP-ACC-REC-005-10 proved_by: [ATS-ACC-REC-005-10] statement: >- Timing-policy changes affect subsequent items without recalculating the dates already assigned to existing items. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-accounting:docs/reconciliation/architecture.md#12.2 Expected settlement date' origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; architecture §12.2) - id: BR-CAP-ACC-REC-005-11 proved_by: [ATS-ACC-REC-005-08, TST-ACC-REC-030, TST-ACC-REC-048] statement: >- Rhythm supplies shared read-only bank holidays and processor timing defaults, bounding lead and grace values at thirty business days. kind: policy enforced_at: - database must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-ACC-REC-005-12 proved_by: [ATS-ACC-REC-005-09, TST-ACC-REC-047] statement: >- Manual entry cannot create payment effects such as captures, refunds or chargebacks; those come from the causing financial workflow. kind: validation enforced_at: - database must_prove: true provenance: test source: >- 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 origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U4)' - id: BR-CAP-ACC-REC-005-13 proved_by: [ATS-ACC-REC-005-11] statement: >- An eligible effect needs an available lead-time and cut-off rule, and recording refuses source keys reserved for manual reconciliation entry. kind: validation enforced_at: - service must_prove: true provenance: observed source: >- services-accounting:modules/reconciliation/services/settlement-items/settlement-item-recording.ts:recordSettlementItem origin: none scenarios: - id: SC-CAP-ACC-REC-005-01 given: A Friday-evening Payrix capture follows the cut-off before a Monday bank holiday. when: Record the financial effect. then: Eligibility and expected arrival fall on the following Tuesday. provenance: test source: >- 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 - id: SC-CAP-ACC-REC-005-02 given: An electronic check awaits clearing. when: Record pending money and later mark clearing. then: Dates remain absent until clearing assigns arrival four business days later. provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#records it with no dates edge_cases: - id: SC-CAP-ACC-REC-005-03 given: One capture effect has already been recorded. when: Observe it again with the same effect key. then: The original item returns without another row. provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/settlement-items/settlement-item-recording.integration.spec.js#leaves one row constraints: [] depends_on: [] related: - CAP-ACC-REC-006 - CAP-ACC-REC-008 - CAP-ACC-REC-017 journeys: - JNY-ACC-REC-004 open_questions: [] evidence: - >- Examined supporting service material: services/settlement-items/settlement-item-recording.ts, settlement-item-commands.ts, persistence/settlement-item-recordings.ts, rules/business-days.ts, rules/item-kinds.ts; db/settlement-items.table.ts, reconciliation-evidence.table.ts (settlement item evidence links), bank-holidays.table.ts, settlement-lead-times.table.ts; transactions callers (dependency only): modules/transactions/services/payments/ports/settlement-items.ts; tests integration settlement-item-recording.integration.spec.js, db/settlement-items, bank-holidays, settlement-lead-times table specs, unit/rules/business-days.spec.js, item-kinds.spec.js. controls: [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] exercised_by: [FAS-ACC-REC-04-01, FAS-ACC-REC-04-02, FAS-ACC-REC-04-03, FAS-ACC-REC-04-05] suites: [TST-ACC-REC-030, TST-ACC-REC-046, TST-ACC-REC-047, TST-ACC-REC-048, TST-ACC-REC-078, TST-ACC-REC-084, TST-ACC-REC-085] --- # 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.