--- id: CAP-ACC-TRX-009 title: Complete invoice settlement with credit and money feature: FEAT-ACC-TRX-03 product_area: accounting module: transactions revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-ACC-PAY-017 - CAP-ACC-PAY-022 - CAP-ACC-PAY-026 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D4' - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D5' - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D6' - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D7' - 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-15' - 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-17' - 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01' purpose: Staff settle several customer invoices through one coordinated request. 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. concepts: - CON-ACC-TRX-003 - CON-ACC-TRX-004 - CON-ACC-TRX-001 actors: - ACT-ACC-012 - ACT-ACC-021 - ACT-ACC-024 surfaces: - console - api - job permissions: - key: accounting.settlements.create where_checked: api scope: tenant - key: accounting.settlements.read where_checked: api scope: tenant - key: accounting.payments.create where_checked: api scope: tenant - key: accounting.credit-applications.create where_checked: api scope: tenant rules: - id: BR-CAP-ACC-TRX-009-01 proved_by: [ATS-ACC-TRX-009-01, TST-ACC-TRX-017] statement: >- Settlement creation requires settlement, payment and credit-application create authority together; reading requires settlement read plus payment or application read authority. kind: permission enforced_at: - api must_prove: true provenance: test source: >- 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) origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-02 proved_by: [ATS-ACC-TRX-009-02, ATS-ACC-TRX-009-03, TST-ACC-TRX-126] statement: >- Settlement targets must share its customer, unit and currency, remain outstanding and receive no more than their current balance. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/transactions/tests/integration/services/settlements/settlements.integration.spec.js#it refuses settling an invoice that owes nothing (nothing_to_allocate) origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-03 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] statement: >- Settlement uses named credits first in request order, then other eligible customer credits oldest first, up to fifty, unless automatic credit use is disabled. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-04 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] statement: >- Chosen credit is reserved until the payment outcome, preventing competing settlements from spending it and releasing it on failure. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- 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 origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-05 proved_by: [ATS-ACC-TRX-006-10, ATS-ACC-TRX-009-06, TST-ACC-TRX-125, TST-ACC-TRX-126] statement: >- 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. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-06 proved_by: [ATS-ACC-TRX-009-07, TST-ACC-TRX-126] statement: >- Overpayment remains unapplied or follows the configured credit policy, can explicitly become credit, or is rejected before writes when refusal is requested. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-9' - id: BR-CAP-ACC-TRX-009-07 proved_by: [ATS-ACC-TRX-009-08, TST-ACC-TRX-122] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-17' - id: BR-CAP-ACC-TRX-009-08 proved_by: [ATS-ACC-TRX-009-09, TST-ACC-TRX-122] statement: >- 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. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-17' - id: BR-CAP-ACC-TRX-009-09 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] statement: >- A definite charge failure releases credit reservations, voids the fee invoice and permits a fresh settlement attempt under the same key. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-10 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] statement: >- Uncertain tender outcomes leave settlement pending; a settlement with no started payment fails after a day and releases reserved credit. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-11 proved_by: [ATS-ACC-TRX-009-12] statement: >- Settlement, receipt, applications and intent retain reciprocal references for following the work across records. kind: invariant enforced_at: - service must_prove: false provenance: test source: >- 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 origin: none note: >- The cited build recommendation does not establish Product approval; the authority gap remains open in FND-ACC-TRX-035. - id: BR-CAP-ACC-TRX-009-12 proved_by: [] statement: >- The console distributes credit before payment against the oldest invoices, selects the default open batch and blocks review until validation succeeds. kind: policy enforced_at: - console must_prove: false provenance: observed source: 'react-console:components/accounting/payments/receive-payment-screen.tsx' origin: none note: The console form computes credit and payment splits and blocks review when validation reports a problem. scenarios: - id: SC-CAP-ACC-TRX-009-01 given: The member has 20.00 of credit and two outstanding invoices. when: Settle both documents with credit and a check. then: Completion consumes credit before applying check money to the remainder. provenance: test source: 'react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0301.spec.ts#ACT-ACC-0301' - id: SC-CAP-ACC-TRX-009-02 given: A settlement reserves credit before a card tender. when: Submit a card that definitely declines. then: Failure releases the credit and leaves the target lines unpaid. provenance: test source: 'react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0317.spec.ts#ACT-ACC-0317' - id: SC-CAP-ACC-TRX-009-03 given: A 100.00 invoice requires a fee under a 2.5 percent plus 0.30 rule. when: Tender the member’s card. then: The 102.80 capture settles both the main invoice and the separate 2.80 fee invoice. provenance: test source: >- 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 edge_cases: [] depends_on: - CAP-ACC-TRX-006 - CAP-ACC-TRX-007 - CAP-ACC-TRX-011 related: - CAP-ACC-TRX-008 journeys: - JNY-ACC-TRX-002 - JNY-ACC-TRX-006 evidence: - >- services-accounting at f47cb263875bbc0c5640fba7dae6785ec32695f8: modules/transactions/aws/api/settlements.routes.ts (settle, getSettlement); services/settlements/settlement-commands.ts, card-fees.ts, settlement-answers.ts; services/payments/intent-sweeper.ts (stale settlements); db/settlements.table.ts; docs/accounting/settlements.md; aws/accounting.service.ts (SETTLEMENT_CREATE_PERMISSIONS, SETTLEMENT_READ_ANY_OF); tests integration/services/settlements/*, e2e/settlements.e2e.spec.js, card-fees.e2e.spec.js. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: app/(console)/console/[tenantId]/accounting/payments/receive, settlements/[settlementId]; components/accounting/payments/receive-payment-screen.tsx; components/accounting/settlements; journeys ACT-ACC-0301, 0316, 0317, 0340, 0343, 0344, 0347, 0355; inventory rules RUL-ACC-PAY-033, 048 to 052, 056, 061, 062, 067 to 069. 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-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] exercised_by: [FAS-ACC-TRX-03-01, FAS-ACC-TRX-03-02, FAS-ACC-TRX-03-04, FAS-ACC-TRX-03-05] suites: [TST-ACC-TRX-017, TST-ACC-TRX-122, TST-ACC-TRX-124, TST-ACC-TRX-125, TST-ACC-TRX-126, TST-ACC-TRX-240, TST-ACC-TRX-252] --- # 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.