--- id: CAP-ACC-REC-007 title: Explain partial or unrecoverable settlement money feature: FEAT-ACC-REC-04 product_area: accounting module: reconciliation revision: 2 status: draft product_intent: proposed implementation_evidence: observed supersedes: - react-console acceptance inventory CAP-ACC-REC-009 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; architecture §12.3 resolved states and §16.3 entry E8) purpose: Approvers need to account for amounts that cannot settle as originally recorded. outcomes: - Partial settlement can be explained across separate deposits. - Write-off records unrecoverable money and its accounting consequence. concepts: - CON-ACC-REC-002 actors: - ACT-ACC-018 surfaces: - api preconditions: [] postconditions: [] permissions: - key: accounting.settlement-items.resolve where_checked: api scope: tenant rules: - id: BR-CAP-ACC-REC-007-01 proved_by: [ATS-ACC-REC-006-09, ATS-ACC-REC-007-01, ATS-ACC-REC-007-08, ATS-ACC-REC-007-09, TST-ACC-REC-012, TST-ACC-REC-024, TST-ACC-REC-047, TST-ACC-REC-071] statement: >- Splitting uses the read version and a request key to create at least two same-sign parts whose amounts exactly equal the original. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses parts that do not total the item (400, `split_parts_total`); services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses a part of the other sign (400, `split_part_sign`); services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses a single part (400, `split_parts_count`); services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses a split whose parts do not total the item; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#answers 200 with the item resolved as split by the caller; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0603.spec.ts#ACT-ACC-0603 origin: none examples: positive: 250.00 split into 200.00 and 50.00. negative: 250.00 split into 200.00 and 49.99 is refused. - id: BR-CAP-ACC-REC-007-02 proved_by: [ATS-ACC-REC-007-02, TST-ACC-REC-024, TST-ACC-REC-071] statement: >- Only unresolved and unclaimed items can be split or resolved; a claimed item’s refusal identifies its reconciliation. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses an item a reconciliation claims, naming it (409, `item_claimed`); services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses a resolved item (409, `item_resolved`); services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses an item claimed by a reconciliation with 409 item_claimed; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses an item a reconciliation claims (409, `item_claimed`) origin: none - id: BR-CAP-ACC-REC-007-03 proved_by: [ATS-ACC-REC-007-03, ATS-ACC-REC-007-10, TST-ACC-REC-071] statement: >- Split marks the original resolved, records the approving person and creates parts retaining the parent’s context and evidence with individual amounts and parent links. kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#writes parts that inherit every fact of the parent, with their own amounts, parent and source keys; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#resolves the parent `split`, by the caller, at the next version; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#gives each part the parent’s evidence files; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#clears the parent’s open overdue-settlement exception; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#records `item.split` with the parts and the versions origin: none - id: BR-CAP-ACC-REC-007-04 proved_by: [ATS-ACC-REC-007-03, ATS-ACC-REC-007-10, TST-ACC-REC-071] statement: Split and write-off close an open overdue exception on the original item. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#clears the parent’s open overdue-settlement exception; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#resolves the parent `split`, by the caller, at the next version; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#writes parts that inherit every fact of the parent, with their own amounts, parent and source keys; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#gives each part the parent’s evidence files; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#records `item.split` with the parts and the versions origin: none - id: BR-CAP-ACC-REC-007-05 proved_by: [ATS-ACC-REC-007-04, ATS-ACC-REC-007-11, ATS-ACC-REC-014-10, TST-ACC-REC-024, TST-ACC-REC-071] statement: Item resolution records a reason and chooses either write-off or another explained resolution. kind: validation enforced_at: - api must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses a resolution outside the vocabulary with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#writes off an item with its entry: Dr the write-off account, Cr the merchant clearing account, in the unit’s batch on its date; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#mirrors the entry of a negative item: Dr the clearing account, Cr the write-off account; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#dates the request on the November batch’s date, the resolution date its document date origin: none - id: BR-CAP-ACC-REC-007-06 proved_by: [ATS-ACC-REC-006-09, ATS-ACC-REC-007-04, ATS-ACC-REC-007-08, ATS-ACC-REC-007-09, ATS-ACC-REC-007-11, ATS-ACC-REC-014-10, TST-ACC-REC-012, TST-ACC-REC-024, TST-ACC-REC-071] statement: >- Write-off creates a request debiting settlement write-off and crediting merchant clearing for a positive item, reversing those sides for a negative item, dated on the selected open batch with the resolution day retained separately. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#writes off an item with its entry: Dr the write-off account, Cr the merchant clearing account, in the unit’s batch on its date; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#mirrors the entry of a negative item: Dr the clearing account, Cr the write-off account; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#dates the request on the November batch’s date, the resolution date its document date; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses a resolution outside the vocabulary with 400; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0603.spec.ts#ACT-ACC-0603 origin: none - id: BR-CAP-ACC-REC-007-07 proved_by: [ATS-ACC-REC-006-09, ATS-ACC-REC-007-05, ATS-ACC-REC-007-08, ATS-ACC-REC-007-09, ATS-ACC-REC-007-12, ATS-ACC-REC-014-14, TST-ACC-REC-012, TST-ACC-REC-071] statement: >- Write-off leaves the item unresolved when the write-off account or an accepting operational batch in an open period is missing. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses a write-off where the unit has no write-off account (409, `write_off_account_missing`); services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#leaves the item unresolved when its write-off is refused (the transaction rolled back); services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses a write-off where the unit has no batch for its request (400, `no_open_batch`); services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#leaves the item unresolved, and asks for nothing, when refused for want of a batch; react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0603.spec.ts#ACT-ACC-0603 origin: none - id: BR-CAP-ACC-REC-007-08 proved_by: [ATS-ACC-REC-007-06, TST-ACC-REC-024, TST-ACC-REC-071] statement: An explained resolution other than write-off creates no ledger request. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#resolves an item otherwise, asking the ledger for nothing; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#answers 200 with the item resolved otherwise by the caller origin: none - id: BR-CAP-ACC-REC-007-09 proved_by: [ATS-ACC-REC-007-07, TST-ACC-REC-024, TST-ACC-REC-071] statement: >- Split and resolution keys replay identical requests, reject changed bodies and distinguish the operations even when their key text matches. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#keys a request per operation: the same key on a split is a request of its own; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses a principal without accounting.settlement-items.resolve with 403; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#answers the same request under the same key with the first answer; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses the same key with another request with 409 idempotency_key_reused; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses a split without an Idempotency-Key with 400 idempotency_key_required origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: idempotency of every money command)' - id: BR-CAP-ACC-REC-007-10 proved_by: [ATS-ACC-REC-007-07, TST-ACC-REC-024, TST-ACC-REC-071] statement: The sensitive administrator resolve permission governs both splitting and item resolution. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses a principal without accounting.settlement-items.resolve with 403; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#answers the same request under the same key with the first answer; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses the same key with another request with 409 idempotency_key_reused; services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#refuses a split without an Idempotency-Key with 400 idempotency_key_required; services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#keys a request per operation: the same key on a split is a request of its own origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions)' - id: BR-CAP-ACC-REC-007-11 proved_by: [] statement: The console currently exposes neither splitting nor write-off. kind: policy enforced_at: - console must_prove: false provenance: observed source: 'react-console:lib/accounting/reconciliation/store.tsx:useReconStore' origin: none scenarios: - id: SC-CAP-ACC-REC-007-01 given: Only two hundred dollars of a two-hundred-fifty-dollar capture arrived. when: Split into arrived money and the fifty-dollar remainder. then: The original becomes resolved as split and both same-context parts replace it. provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#answers the two parts with their amounts and source keys :split: - id: SC-CAP-ACC-REC-007-02 given: The unit’s write-off account is configured. when: Write off the overdue item. then: Resolution creates a clearing-to-write-off accounting request. provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#writes the request settlement-item::write-off in beta’s batch, debiting the write-off account and crediting the clearing account edge_cases: - id: SC-CAP-ACC-REC-007-03 given: The only operational batch is dated in a closed October. when: Attempt write-off. then: 'No accepting open-period batch exists, so the item remains unresolved.' provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/settlement-items.integration.spec.js#refuses the write-off while the unit’s batch is dated in the closed October (400, `no_open_batch`) constraints: [] depends_on: - CAP-ACC-REC-005 - CAP-ACC-REC-014 related: - CAP-ACC-REC-006 - CAP-ACC-REC-015 journeys: - JNY-ACC-REC-004 open_questions: [] evidence: - >- Examined supporting service material: outstanding.routes.ts (splitSettlementItem, resolveSettlementItem), outstanding.schemas.ts, services/persistence/settlement-items.ts (split and resolve), rules/posting-plans.ts (write-off); tests e2e/outstanding.e2e.spec.js, integration settlement-items.integration.spec.js, db/settlement-items.table.integration.spec.js, unit/rules/posting-plans.spec.js. - >- Examined supporting console material: lib/accounting/reconciliation/client.ts (items.resolve, unused by the store); acceptance journey ACT-ACC-0603. controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-DAT-001, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005] exercised_by: [FAS-ACC-REC-04-02, FAS-ACC-REC-04-03, FAS-ACC-REC-04-04] suites: [TST-ACC-REC-012, TST-ACC-REC-024, TST-ACC-REC-047, TST-ACC-REC-071] --- # Explain partial or unrecoverable settlement money ## Purpose Approvers need to account for amounts that cannot settle as originally recorded. ## How It Works An approver inspects the item and confirms that no explanation still holds it. A partial settlement can be separated into parts retaining the original context. Unrecoverable money can be written off when accounting setup is complete. An alternative explained resolution can conclude the expectation without a write-off request. Missing accounts or an accepting batch leave the money unresolved for further work. ## Relationships Outstanding inspection identifies the money, ledger requests carry write-off accounting and exceptions retain or clear the associated concern.