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.

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: Partial settlement can be explained across separate deposits.Write-off records unrecoverable money and its accounting consequence.
Surfaces: api
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)

Controls

23 controls apply, from the corpus control catalogue.

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

Permissions

Key	Checked at	Scope
`accounting.settlement-items.resolve`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Splitting uses the read version and a request key to create at least two same-sign parts whose amounts exactly equal the original. ✓ 250.00 split into 200.00 and 50.00.✗ 250.00 split into 200.00 and 49.99 is refused. 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`	validation	api, service, database	test 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
`02`must prove Proposed	Only unresolved and unclaimed items can be split or resolved; a claimed item’s refusal identifies its reconciliation. proved by `ATS-ACC-REC-007-02`, `TST-ACC-REC-024`, `TST-ACC-REC-071`	policy	service	test 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`)
`03`must prove Proposed	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. proved by `ATS-ACC-REC-007-03`, `ATS-ACC-REC-007-10`, `TST-ACC-REC-071`	lifecycle	service, database	test 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
`04`must prove Proposed	Split and write-off close an open overdue exception on the original item. proved by `ATS-ACC-REC-007-03`, `ATS-ACC-REC-007-10`, `TST-ACC-REC-071`	lifecycle	service	test 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
`05`must prove Proposed	Item resolution records a reason and chooses either write-off or another explained resolution. 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`	validation	api	test 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
`06`must prove Proposed	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. 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`	calculation	service	test 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
`07`must prove Proposed	Write-off leaves the item unresolved when the write-off account or an accepting operational batch in an open period is missing. 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`	validation	service	test 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
`08`must prove Proposed	An explained resolution other than write-off creates no ledger request. proved by `ATS-ACC-REC-007-06`, `TST-ACC-REC-024`, `TST-ACC-REC-071`	policy	service	test 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
`09`must prove Proposed	Split and resolution keys replay identical requests, reject changed bodies and distinguish the operations even when their key text matches. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: idempotency of every money command) proved by `ATS-ACC-REC-007-07`, `TST-ACC-REC-024`, `TST-ACC-REC-071`	validation	api, service	test 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
`10`must prove Proposed	The sensitive administrator resolve permission governs both splitting and item resolution. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions) proved by `ATS-ACC-REC-007-07`, `TST-ACC-REC-024`, `TST-ACC-REC-071`	permission	api	test 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
`11` Proposed	The console currently exposes neither splitting nor write-off.	policy	console	observed react-console:lib/accounting/reconciliation/store.tsx:useReconStore

Scenarios

Id	Given	When	Then	Provenance
`01`	Only two hundred dollars of a two-hundred-fifty-dollar capture arrived.	Split into arrived money and the fifty-dollar remainder.	The original becomes resolved as split and both same-context parts replace it.	test services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#answers the two parts with their amounts and source keys <parent>:split:<n>
`02`	The unit’s write-off account is configured.	Write off the overdue item.	Resolution creates a clearing-to-write-off accounting request.	test services-accounting:modules/reconciliation/tests/e2e/outstanding.e2e.spec.js#writes the request settlement-item:<id>:write-off in beta’s batch, debiting the write-off account and crediting the clearing account

Edge Cases

Id	Given	When	Then	Provenance
`03`	The only operational batch is dated in a closed October.	Attempt write-off.	No accepting open-period batch exists, so the item remains unresolved.	test 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`)

Planning

Implementation

Explain partial or unrecoverable settlement money ​

Purpose ​

How It Works ​

Relationships ​