Complete invoice settlement with credit and money

Purpose

Staff settle several customer invoices through one coordinated request.

How It Works

Staff review outstanding invoices and choose available credit before entering a tender. Accounting reserves the credit needed while payment is in progress. A successful request retains links among settlement, payment and applications. Required processing fees become their own invoice within the tender. Definite failure releases reservations and compensates the fee document. An uncertain processor answer leaves the request pending until resolution. Completion explains any money the invoices did not consume.

Relationships

Record receipts collected outside Rhythm supplies or continues the related financial work.
Collect processor payments and resolve uncertainty supplies or continues the related financial work.
Provide and spend customer credit supplies or continues the related financial work.
Allocate and relocate received money supplies or continues the related financial work.

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: Staff settle several customer invoices through one coordinated request.An uncertain processor answer leaves the request pending until resolution. Completion explains any money the invoices did not consume.
Surfaces: consoleapijob
Intent sources: services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D4services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D5services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D6services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D7services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-15services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-17services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01

Controls

29 controls apply, from the corpus control catalogue.

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-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-VEN-001 TC-VEN-002 TC-VEN-003 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`accounting.settlements.create`	api	tenant
`accounting.settlements.read`	api	tenant
`accounting.payments.create`	api	tenant
`accounting.credit-applications.create`	api	tenant

Business Rules

12 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	Settlement creation requires settlement, payment and credit-application create authority together; reading requires settlement read plus payment or application read authority. proved by `ATS-ACC-TRX-009-01`, `TST-ACC-TRX-017`	permission	api	test services-accounting:modules/transactions/tests/e2e/settlements.e2e.spec.js#it is refused the settle route as a reader and the settlement read as an outsider (403)
`02`must prove Proposed	Settlement targets must share its customer, unit and currency, remain outstanding and receive no more than their current balance. proved by `ATS-ACC-TRX-009-02`, `ATS-ACC-TRX-009-03`, `TST-ACC-TRX-126`	validation	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlements.integration.spec.js#it refuses settling an invoice that owes nothing (nothing_to_allocate)
`03`must prove Proposed	Settlement uses named credits first in request order, then other eligible customer credits oldest first, up to fifty, unless automatic credit use is disabled. proved by `ATS-ACC-TRX-006-10`, `ATS-ACC-TRX-008-09`, `ATS-ACC-TRX-009-04`, `ATS-ACC-TRX-009-12`, `ATS-ACC-TRX-011-10`, `TST-ACC-TRX-126`, `TST-ACC-TRX-240`	calculation	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlements.integration.spec.js#it applies the open credit’s 500 first and takes a check of 8000 for the rest: completed with its payment
`04`must prove Proposed	Chosen credit is reserved until the payment outcome, preventing competing settlements from spending it and releasing it on failure. proved by `ATS-ACC-TRX-008-09`, `ATS-ACC-TRX-009-05`, `ATS-ACC-TRX-009-12`, `ATS-ACC-TRX-009-13`, `ATS-ACC-TRX-011-10`, `ATS-ACC-TRX-020-09`, `TST-ACC-TRX-124`, `TST-ACC-TRX-126`, `TST-ACC-TRX-252`	invariant	service, database	test services-accounting:modules/transactions/tests/integration/services/settlements/settlements.integration.spec.js#it refuses with the decline (processor_declined), the settlement failed with the code, the reservation released, nothing applied
`05`must prove Proposed	Credits can complete settlement alone; any supplied payment must be positive, and a payment supplied after full credit coverage is retained entirely unapplied with that outcome disclosed. proved by `ATS-ACC-TRX-006-10`, `ATS-ACC-TRX-009-06`, `TST-ACC-TRX-125`, `TST-ACC-TRX-126`	policy	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlement-unapplied.integration.spec.js#it leaves the check’s whole 5000 unapplied and says so plainly in the answer
`06`must prove Proposed	Overpayment remains unapplied or follows the configured credit policy, can explicitly become credit, or is rejected before writes when refusal is requested. origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-9 proved by `ATS-ACC-TRX-009-07`, `TST-ACC-TRX-126`	policy	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlements.integration.spec.js#it completes with an overpayment credit of 1000 made from the payment, the payment’s unapplied money gone into it
`07`must prove Proposed	Required or accepted optional card fees apply the unit’s percentage, fixed amount and minimum once across eligible tender value through a separate fee invoice settled with the tender. origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-17 proved by `ATS-ACC-TRX-009-08`, `TST-ACC-TRX-122`	calculation	service	test services-accounting:modules/transactions/tests/integration/services/settlements/card-fees.integration.spec.js#it shares one fee over two required invoices in proportion, the fixed amount charged once: 20000 at 2.5% + 30 is 530
`08`must prove Proposed	A declined required fee or missing required fee configuration blocks charging; offline money is fee-free and bank debits are fee-free when excluded by the unit rule. origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-17 proved by `ATS-ACC-TRX-009-09`, `TST-ACC-TRX-122`	validation	service	test services-accounting:modules/transactions/tests/integration/services/settlements/card-fees.integration.spec.js#it refuses the settlement with card_fee_required naming the invoice, and writes nothing
`09`must prove Proposed	A definite charge failure releases credit reservations, voids the fee invoice and permits a fresh settlement attempt under the same key. proved by `ATS-ACC-TRX-007-12`, `ATS-ACC-TRX-009-05`, `ATS-ACC-TRX-009-10`, `TST-ACC-TRX-122`, `TST-ACC-TRX-124`, `TST-ACC-TRX-126`, `TST-ACC-TRX-252`	lifecycle	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlement-retry.integration.spec.js#it runs a new attempt under the key: a new settlement, completed with a payment, stored under the key with its attempt number
`10`must prove Proposed	Uncertain tender outcomes leave settlement pending; a settlement with no started payment fails after a day and releases reserved credit. proved by `ATS-ACC-TRX-007-12`, `ATS-ACC-TRX-009-11`, `ATS-ACC-TRX-009-12`, `ATS-ACC-TRX-012-12`, `ATS-ACC-TRX-013-10`, `ATS-ACC-TRX-020-09`, `TST-ACC-TRX-126`	lifecycle	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlements.integration.spec.js#it is failed abandoned by the sweeper a day later, the reservation released
`11` Proposed	Settlement, receipt, applications and intent retain reciprocal references for following the work across records. proved by `ATS-ACC-TRX-009-12`	invariant	service	test services-accounting:modules/transactions/tests/integration/services/settlements/settlement-linkage.integration.spec.js#it names its settlement on the payment and on the intent it made
`12` Proposed	The console distributes credit before payment against the oldest invoices, selects the default open batch and blocks review until validation succeeds.	policy	console	observed react-console:components/accounting/payments/receive-payment-screen.tsx

Scenarios

Id	Given	When	Then	Provenance
`01`	The member has 20.00 of credit and two outstanding invoices.	Settle both documents with credit and a check.	Completion consumes credit before applying check money to the remainder.	test react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0301.spec.ts#ACT-ACC-0301
`02`	A settlement reserves credit before a card tender.	Submit a card that definitely declines.	Failure releases the credit and leaves the target lines unpaid.	test react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0317.spec.ts#ACT-ACC-0317
`03`	A 100.00 invoice requires a fee under a 2.5 percent plus 0.30 rule.	Tender the member’s card.	The 102.80 capture settles both the main invoice and the separate 2.80 fee invoice.	test services-accounting:modules/transactions/tests/integration/services/settlements/card-fees.integration.spec.js#it charges 10280 in one tender: the invoice and the fee of 280 (2.5% + 30) both paid, the step card_fee done, the fee invoice answered

Planning

Implementation

Complete invoice settlement with credit and money ​

Purpose ​

How It Works ​

Relationships ​