--- id: CAP-ACC-REC-010 title: Document processor deductions and corrections feature: FEAT-ACC-REC-02 product_area: accounting module: reconciliation revision: 2 status: draft product_intent: confirmed implementation_evidence: observed supersedes: - react-console acceptance inventory CAP-ACC-REC-004 (manual items) source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: hand-entered fees, reserves and corrections with their accounts) - 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U4, U5, U6, U9)' - >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-18, INV-19) purpose: Preparers need to explain processor effects that payment records do not contain. outcomes: - Processor adjustments retain their supporting documentation. - Fee-only and zero bank movements remain explainable. concepts: - CON-ACC-REC-003 - CON-ACC-REC-002 actors: - ACT-ACC-017 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: accounting.reconciliation-batches.update where_checked: api scope: tenant - key: accounting.reconciliation-batches.update where_checked: console scope: tenant rules: - id: BR-CAP-ACC-REC-010-01 proved_by: [ATS-ACC-REC-010-01, TST-ACC-REC-059] statement: >- Manual entries are restricted to fees, fee refunds, reserve holds or releases and adjustments with the required sign, reporting invalid kind, sign and documentation together. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses a manual item without a note or evidence, of a kind not entered by hand, and of the wrong sign, all at once; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses a capture entered by hand with 400 origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U4, U6)' - id: BR-CAP-ACC-REC-010-02 proved_by: [ATS-ACC-REC-010-02, TST-ACC-REC-039] statement: >- Each manual entry needs a note or evidence at commit, and its final evidence cannot be removed without a note remaining. kind: validation enforced_at: - database must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#refuses at commit a manual fee with neither a note nor an evidence file (RHF34); services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#commits a manual fee written with an evidence file in the same transaction; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#commits a manual fee that carries a note and no evidence file; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#refuses at commit the removal of the only evidence file of a manual fee without a note (RHF34); services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#lets a manual fee’s evidence file go once the fee carries a note origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-18) - id: BR-CAP-ACC-REC-010-03 proved_by: [ATS-ACC-REC-010-03, TST-ACC-REC-047, TST-ACC-REC-059] statement: >- An adjustment selects a ledger account in the reconciliation’s business unit, while fee and reserve recognition uses that unit’s default accounts at finalization. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses an adjustment without a GL account, or with another unit’s, with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#enters an adjustment booked to a GL account of the unit; services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses an adjustment without its GL account origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U5: “other” also names a GL account) - id: BR-CAP-ACC-REC-010-04 proved_by: [ATS-ACC-REC-008-13, ATS-ACC-REC-010-04, ATS-ACC-REC-010-12, TST-ACC-REC-059] statement: >- Adding a manual entry creates a settlement item already claimed by its reconciliation and updates totals and version. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#writes the fee as a manual item of the batch, claimed by it; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#counts the manual item and its claim in the batch, one version on; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#records batch.manual-item-added with the item and its idempotency key; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#answers a repeat of the same key and body with the first answer, entering nothing more; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses the same key with another body with 409 idempotency-key-reused origin: none - id: BR-CAP-ACC-REC-010-05 proved_by: [ATS-ACC-REC-010-05] statement: A manual entry’s occurrence is local midnight on the earliest linked payout’s accounting day. kind: calculation enforced_at: - service must_prove: true provenance: observed source: >- services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:addManualItem origin: none - id: BR-CAP-ACC-REC-010-06 proved_by: [ATS-ACC-REC-008-13, ATS-ACC-REC-010-04, ATS-ACC-REC-010-12, TST-ACC-REC-059] statement: >- Manual addition replays the first entry for an identical request key and body, and rejects a different body under that key. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#answers a repeat of the same key and body with the first answer, entering nothing more; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#writes the fee as a manual item of the batch, claimed by it; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#counts the manual item and its claim in the batch, one version on; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#records batch.manual-item-added with the item and its idempotency key; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses the same key with another body with 409 idempotency-key-reused origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: idempotency of every money command)' - id: BR-CAP-ACC-REC-010-07 proved_by: [ATS-ACC-REC-009-11, ATS-ACC-REC-010-06, ATS-ACC-REC-010-11, TST-ACC-REC-027, TST-ACC-REC-059] statement: >- Removal withdraws the manual item, identifies its reconciliation, updates current totals and version but retains the lifetime manual-entry count; repeating removal finds no active entry. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#resolves the item withdrawn, naming the batch; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#takes it out of the batch’s items and totals, one version on, keeping the count of items entered; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses to remove it again with 404; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#leaves the removed fee withdrawn origin: none - id: BR-CAP-ACC-REC-010-08 proved_by: [ATS-ACC-REC-010-07, TST-ACC-REC-036] statement: The lifetime manual-entry limit is two hundred per reconciliation. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a 201st manual item origin: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-19) - id: BR-CAP-ACC-REC-010-09 proved_by: [ATS-ACC-REC-010-08, TST-ACC-REC-028, TST-ACC-REC-059] statement: >- Manual entries can explain a negative fee-only deposit or help reconcile a deposit whose net amount is zero. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#balances the negative payout with the two manual items; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 14: reconciles and finalizes a zero payout whose fee took the whole capture origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U9)' - id: BR-CAP-ACC-REC-010-10 proved_by: [] statement: >- The adjustment dialog leaves the amount for staff to enter, explains its sign, requests kind and note plus an adjustment account when needed, and has no working evidence upload. kind: policy enforced_at: - console must_prove: false provenance: observed source: 'react-console:components/accounting/reconciliation/workspace/adjustments.tsx:AddAdjustment' origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U5, U6)' - id: BR-CAP-ACC-REC-010-11 proved_by: [ATS-ACC-REC-010-09, TST-ACC-REC-016] statement: Reconciliation update permission is required to add or remove manual entries. kind: permission enforced_at: - api must_prove: true provenance: observed source: 'services-accounting:modules/reconciliation/aws/api/matching.routes.ts:addReconciliationManualItem' origin: 'services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions)' scenarios: - id: SC-CAP-ACC-REC-010-01 given: 'Ten thousand dollars of claimed money explains a $9,725.00 deposit before deductions.' when: Add the documented two-hundred-twenty-five-dollar fee and fifty-dollar reserve hold. then: The open explanation becomes Balanced at zero difference. provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 6: balances to a difference of 0 with the fee and the reserve hold, and shows Balanced - id: SC-CAP-ACC-REC-010-02 given: The processor debits fifteen dollars for fees alone. when: Enter the negative-fifteen-dollar fee. then: The explanation balances for approval. provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 14: reconciles and finalizes a negative payout of −1500 made of fees only edge_cases: - id: SC-CAP-ACC-REC-010-03 given: 'A three-hundred-fifty-dollar capture is entirely consumed by its fee, producing a zero payout.' when: Claim the capture and add its negative fee. then: Approval recognizes the fee without a bank transfer. provenance: test source: >- services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 14: reconciles and finalizes a zero payout whose fee took the whole capture constraints: [] depends_on: - CAP-ACC-REC-008 related: - CAP-ACC-REC-009 - CAP-ACC-REC-011 - CAP-ACC-REC-014 journeys: - JNY-ACC-REC-001 open_questions: [] evidence: - >- Examined supporting service material: matching.routes.ts (addReconciliationManualItem, removeReconciliationManualItem), matching.schemas.ts (manualItemBodySchema), services/persistence/reconciliation-allocations.ts (manual items), rules/item-kinds.ts; db/settlement-items.table.ts, reconciliation-evidence.table.ts; tests integration reconciliation-allocations.integration.spec.js, db reconciliation-evidence-files and settlement-items table specs, e2e/reconciliation-matching.e2e.spec.js; modules/reconciliation/README.md (rules repaired 2026-10-19). - >- Examined supporting console material: components/accounting/reconciliation/workspace/adjustments.tsx; lib/accounting/reconciliation/adapter.ts (toManualItemBody), adapter.test.ts; acceptance journey ACT-ACC-0596. controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-ACC-REC-02-01, FAS-ACC-REC-02-02, FAS-ACC-REC-02-03, FAS-ACC-REC-02-04, FAS-ACC-REC-02-05] suites: [TST-ACC-REC-016, TST-ACC-REC-027, TST-ACC-REC-028, TST-ACC-REC-036, TST-ACC-REC-039, TST-ACC-REC-047, TST-ACC-REC-059] --- # Document processor deductions and corrections ## Purpose Preparers need to explain processor effects that payment records do not contain. ## How It Works The preparer chooses a fee, reserve movement or adjustment and enters its signed amount. A note or supporting evidence gives the approver a basis for review. Rhythm creates the financial item and associates it with the open explanation. Removing a mistaken entry withdraws it without pretending it never existed. Missing documentation, invalid accounts or limits stop entry, and console evidence upload remains incomplete. ## Relationships The matching workspace contains entries, finalization creates their recognition and operational posting writes the requested accounting.