Correct payout records while preserving finalized money

Purpose

Finance staff need to repair entry errors and retain a visible cancellation history.

How It Works

A bookkeeper reviews the payout before replacing editable information. Rhythm checks the version and whether an active explanation restricts the requested change. An amount correction carries through to an open draft rather than leaving the explanation behind. A mistaken unheld entry can instead be voided with a reason. Finalized money requires correction through the reconciliation’s reversal workflow.

Relationships

Creation supplies the payout; draft abandonment releases its holdings; finalized corrections proceed through reversal.

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: Corrections remain versioned and update the open explanation.Cancellation preserves the entry and releases its reference.Finalized financial details remain protected.
Surfaces: api
Intent sources: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2 payouts: correction, void)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: architecture §6 INV-08, INV-09)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D1 (no silent edits after finalize)

Controls

24 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-DAT-004 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.payouts.update`	api	tenant
`accounting.payouts.delete`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Payout correction replaces the editable fields using the saved version, clears omitted optional values and rejects a stale version. 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-002-01`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	validation	api, service	test services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#replaces the editable fields at the next version, stamped by the editor; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#answers the payout at the next version with its new fields; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a replacement at another version with 409; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a reference another live payout of the merchant account has; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a bank account of another business unit
`02`must prove Confirmed	Correction applies the original duplicate and bank compatibility checks, refusing an occupied live reference or a bank from another unit. 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-002-01`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	validation	service, database	test services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a reference another live payout of the merchant account has; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#answers the payout at the next version with its new fields; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a replacement at another version with 409; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a bank account of another business unit
`03`must prove Confirmed	An amount correction updates the open reconciliation’s linked amount, payout total, difference and version in the same transaction, and records that change. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope); journey 0593 proved by `ATS-ACC-REC-002-02`, `ATS-ACC-REC-002-09`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	calculation	service, database	test services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#carries a new amount into the open batch’s link and payouts total, bumping the batch’s version; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#records the open batch’s change with the edit; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#recomputes the open batch’s payouts total from the new amount
`04`must prove Confirmed	The service refuses correction, verification, void and evidence attachment after finalization; the database protects financial fields while allowing a note-only change. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-09) proved by `ATS-ACC-REC-002-03`, `TST-ACC-REC-025`, `TST-ACC-REC-033`	invariant	service, database	observed services-accounting:modules/reconciliation/services/persistence/payouts.ts:updatePayout
`05`must prove Confirmed	A payout’s currency and entry origin remain fixed after creation. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-02) proved by `ATS-ACC-REC-002-03`, `TST-ACC-REC-025`, `TST-ACC-REC-033`	invariant	database	test services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses a change to the currency (write-once); services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a payout in a finalized reconciliation with 409 payout-reconciled; services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses a change to the amount of a payout in a finalized batch (INV-09); services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses a change to the accounting date of a payout in a finalized batch; services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#lets a payout in a finalized batch take a note; services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses a change to the origin (write-once)
`06`must prove Confirmed	Void requires a reason and request key and fails while an open or finalized reconciliation holds the payout; an already voided payout has no further lifecycle actions. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (plan approved 2026-10-22 10:40 ET; §2 scope); journey 0593 proved by `ATS-ACC-REC-001-12`, `ATS-ACC-REC-002-04`, `ATS-ACC-REC-002-10`, `ATS-ACC-REC-012-07`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	lifecycle	api, service	test services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a payout in an open reconciliation with payout-in-reconciliation; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a payout in an open reconciliation with 409 payout-in-reconciliation; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a payout in a finalized reconciliation with payout-reconciled; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#answers the payout voided with its reason; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#answers the same voided payout for the same key and body; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a payout already voided with payout-voided; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#voids the payout with its reason, stamped by the voider, and allows it nothing more
`07`must prove Confirmed	A void preserves the payout and its recorded reason for review in the list. 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-001-12`, `ATS-ACC-REC-002-04`, `ATS-ACC-REC-002-10`, `ATS-ACC-REC-012-07`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	lifecycle	service	test services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#voids the payout with its reason, stamped by the voider, and allows it nothing more; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a payout in an open reconciliation with 409 payout-in-reconciliation; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a payout in a finalized reconciliation with payout-reconciled; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#answers the payout voided with its reason; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#answers the same voided payout for the same key and body; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a payout already voided with payout-voided
`08`must prove Confirmed	Evidence is limited to fifty distinct files per payout and cannot be added after void or reconciliation. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-19) proved by `ATS-ACC-REC-002-05`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	validation	service, database	test services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a fifty-first file with evidence-limit; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses the same asset twice with 409 evidence-already-attached; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#refuses a voided payout with payout-voided; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a payout in a finalized reconciliation with 409 payout-reconciled
`09`must prove Confirmed	State controls the offered actions: an unheld payout allows all lifecycle commands, an open-held payout excludes void, and a finalized or voided payout allows none. 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-002-06`, `TST-ACC-REC-090`	policy	service	test services-accounting:modules/reconciliation/tests/unit/rules/payout-rules.spec.js#allows all but void in an open reconciliation; services-accounting:modules/reconciliation/tests/unit/rules/payout-rules.spec.js#allows every command outside a reconciliation; services-accounting:modules/reconciliation/tests/unit/rules/payout-rules.spec.js#allows nothing in a finalized reconciliation; services-accounting:modules/reconciliation/tests/unit/rules/payout-rules.spec.js#allows nothing once voided
`10`must prove Confirmed	Payout deletion is prohibited except during complete workspace purge. proved by `ATS-ACC-REC-002-07`, `TST-ACC-REC-033`	invariant	database	test services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses the owner a delete outside a tenant purge; services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#refuses the application role a delete (no DELETE privilege); services-accounting:modules/reconciliation/tests/integration/db/payouts.table.integration.spec.js#lets the owner delete inside a tenant purge
`11`must prove Confirmed	Update governs correction and evidence, delete governs void, and audit history records the correction’s changed fields and the void. origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions) proved by `ATS-ACC-REC-002-08`, `TST-ACC-REC-025`, `TST-ACC-REC-057`	permission	api	test services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a principal without accounting.payouts.delete with 403; services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a principal without accounting.payouts.update with 403; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#records the edit with the fields it changed and the versions; services-accounting:modules/reconciliation/tests/integration/services/persistence/payouts.integration.spec.js#records the void with its reason and key

Scenarios

Id	Given	When	Then	Provenance
`01`	An open draft holds the payout.	Request payout void.	The active reconciliation prevents void.	test services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#refuses a payout in an open reconciliation with 409 payout-in-reconciliation
`02`	The sample deposit belongs to a finalized explanation.	Replace its amount.	The service refuses correction of reconciled money.	test services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 13: refuses an edit of the finalized payout’s amount with 409 payout-reconciled

Edge Cases

Id	Given	When	Then	Provenance
`03`	An open explanation includes the payout.	Correct its reported amount.	The draft’s payout total updates with that correction.	test services-accounting:modules/reconciliation/tests/e2e/payouts.e2e.spec.js#recomputes the open batch’s payouts total from the new amount

Planning

Implementation

Correct payout records while preserving finalized money ​

Purpose ​

How It Works ​

Relationships ​