--- id: WF-ACC-TRX-008 title: Settle a customer’s invoices with credit and money trigger: >- Staff or Commerce submit a coordinated request to settle customer invoice lines. product_area: accounting module: transactions revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-ACC-TRX-009 - CAP-ACC-TRX-011 - CAP-ACC-TRX-007 moves: - STATE-ACC-TRX-008 - STATE-ACC-TRX-012 - STATE-ACC-TRX-005 - STATE-ACC-TRX-001 crosses: - SVC-ACC-TRX-transactions hops: - 'n': 1 actor_or_service: Settlement (resolve and reserve) action: >- Lock customer targets, recognise selected quotations and reserve named credit followed by automatic oldest-first credit; this path omits expiry and order-category checks. anchor: >- services-accounting:modules/transactions/services/settlements/settlement-commands.ts:settle seam: sync on_failure: >- Reject validation, including requested excess refusal, and roll back preparation. left_inconsistent: The complete transaction is undone. observer: The API response reports the outcome and applicable refusal code. provenance: observed source: >- services-accounting:modules/transactions/services/settlements/settlement-commands.ts:settle - 'n': 2 actor_or_service: Card fees action: >- Create the applicable one-line fee invoice in the settlement batch and include it in planned collection. anchor: >- services-accounting:modules/transactions/services/settlements/card-fees.ts:issueCardFeeInvoice seam: sync on_failure: Reject the command without retained effects. left_inconsistent: The complete transaction is undone. observer: The API response reports the outcome and applicable refusal code. provenance: observed source: >- services-accounting:modules/transactions/services/settlements/card-fees.ts:issueCardFeeInvoice; 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 - 'n': 3 actor_or_service: Payment receive action: >- Use a derived key to record an offline receipt or start a processor intent. anchor: >- services-accounting:modules/transactions/services/payments/payment-receive.ts:receivePayment seam: sync on_failure: >- Compensate definite failure; retain pending settlement for an uncertain outcome. left_inconsistent: Preparation has already recognised the quotations as receivables. observer: The API response reports the outcome and applicable refusal code. provenance: observed source: >- services-accounting:modules/transactions/services/payments/payment-receive.ts:receivePayment; 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 - 'n': 4 actor_or_service: Settlement completion action: >- Apply capped credit and receipt lines during completion, then retain excess or turn it into credit according to treatment. anchor: >- services-accounting:modules/transactions/services/settlements/settlement-commands.ts:completeSettlement seam: sync on_failure: >- Retain captured excess, marking an exception only for refusal treatment; otherwise keep it unapplied or create the requested credit. left_inconsistent: Captured money remains available for later allocation. observer: The settlement result and recorded exception expose the remaining money. provenance: observed source: >- services-accounting:modules/transactions/services/settlements/settlement-commands.ts:completeSettlement - 'n': 5 actor_or_service: Settlement failure action: >- Compensate definite failure by releasing pending applications, cancelling the fee invoice and retaining a failed attempt with its key released. anchor: >- services-accounting:modules/transactions/services/settlements/settlement-commands.ts:failSettlement seam: sync on_failure: This hop does not define a separate failure branch. left_inconsistent: Failure retains the earlier quotation conversion. observer: The API response reports the outcome and applicable refusal code. provenance: observed source: >- services-accounting:modules/transactions/services/settlements/settlement-commands.ts:failSettlement; 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 idempotency: >- Derived keys protect conversion, collection and excess-credit steps. A failed attempt retains history and permits a numbered replacement attempt under the caller key. concurrency: >- Identity-ordered invoice locks protect preparation; credit reservations protect held value and completion caps target amounts. branches: - >- Credit-only settlement can complete without a receipt; additional receipt money may remain entirely unapplied. waits: - >- Collection uncertainty delays completion; a pending request with no intent can fail after a day. evidence: - >- services-accounting at f47cb263: services/settlements/settlement-commands.ts, card-fees.ts; services/allocation-plan.ts; services/invoices/invoice-issue.ts (convertProForma). - >- react-console at baf6dae3: components/accounting/payments/receive-payment-screen.tsx. controls: [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-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, 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] --- # Settle a customer’s invoices with credit and money ## What It Does Settlement combines credit use and money collection while keeping their independent documents. Failed collection retains earlier quotation conversion, and captured-excess exceptions depend on requested treatment. ## The Flow ```mermaid flowchart TD h0["Settlement (resolve and reserve)"] h1["Card fees"] h0 --> h1 h2["Payment receive"] h1 --> h2 h3["Settlement completion"] h2 --> h3 h4["Settlement failure"] h3 --> h4 ``` The numbered hops identify the participating services, synchronization boundary and evidence. Branch conditions in the frontmatter explain where preparation, completion and recovery diverge. ## When Something Fails Each hop records its rollback, retry or compensation boundary and the result visible to callers or operators. External outcomes can remain unresolved after local preparation commits; the listed recovery behavior defines what remains pending. ## Open Design Questions Bring settlement credit eligibility into agreement with direct application and decide the required compensation for quotation conversion.