---
id: STATE-ACC-TRX-008
title: Settlement operation
object: DOM-ACC-TRX-003
product_area: accounting
module: transactions
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: not created
    meaning: No coordinated settlement exists.
  - name: pending
    meaning: Credit is held while collection is prepared or unresolved.
  - name: completed
    meaning: Credit application and any receipt processing have finished.
  - name: completed with exception
    meaning: Captured excess remains when refusal of excess was requested.
  - name: failed
    meaning: Collection failed or was abandoned and credit reservations were released.
transitions:
  - from: not created
    to: completed
    trigger: settle without delayed processor work
    guard: >-
      Customer, unit, currency and target balances must agree; fee policy must
      be satisfied.
    side_effects:
      - convert quotations
      - reserve and apply selected credit
      - record any receipt and allocations
      - apply excess treatment
    who: >-
      Staff with settlement, payment and application creation permissions or the
      Commerce tender function.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/settlements/settlement-commands.ts;
      services-accounting:modules/transactions/db/settlements.table.ts;
      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
  - from: not created
    to: pending
    trigger: start settlement collection
    guard: 'The same target, accounting and fee checks apply.'
    side_effects:
      - create pending credit reservations
      - issue any fee invoice
      - start the collection intent
    who: Authorized staff or the Commerce tender function.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/settlements/settlement-commands.ts;
      services-accounting:modules/transactions/db/settlements.table.ts;
      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
  - from: pending
    to: completed
    trigger: finish successful collection
    guard: The payment outcome must be successful.
    side_effects:
      - apply capped reserved-credit lines
      - record capped payment allocations
      - create overpayment credit where requested
    who: 'The collection call, replay or scheduled recovery.'
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/settlements/settlement-commands.ts;
      services-accounting:modules/transactions/db/settlements.table.ts;
      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
  - from: pending
    to: failed
    trigger: end unsuccessful settlement
    guard: >-
      A definite collection failure, abandoned intent or day-old missing intent
      is established.
    side_effects:
      - cancel pending credit applications
      - cancel the fee invoice
      - release the key for another attempt
    who: The collection call or scheduled recovery.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/settlements/settlement-commands.ts;
      services-accounting:modules/transactions/db/settlements.table.ts;
      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
  - from: pending
    to: completed with exception
    trigger: retain a capture shortfall exception
    guard: Receipt money remains unapplied and excess treatment requested refusal.
    side_effects:
      - retain the remaining receipt money
      - apply reserved credits with capped lines and record the exception
    who: The collection call or scheduled recovery.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/settlements/settlement-commands.ts:completeSettlement
invalid:
  - from: failed
    to: pending
    why: >-
      Another try retains the failed operation and creates a separate settlement
      attempt.
  - from: completed
    to: pending
    why: A finished settlement does not return to preparation.
concurrency: >-
  Target resolution locks invoices in identity order and pending applications
  reserve credit. Completion caps applications and allocations at the balances
  then remaining.
invariants:
  - INV-DOM-ACC-TRX-003-16
evidence:
  - >-
    services-accounting at f47cb263:
    services/settlements/settlement-commands.ts, card-fees.ts;
    db/settlements.table.ts, payment-vocabularies.ts (settlement steps,
    operation statuses); docs/architecture/accounting-2.0/05-lifecycles.md §5.
---
# Settlement operation

## The Lifecycle

Settlement coordinates independent credit and receipt documents. Captured excess produces an exception only for refusal treatment; normal leave-unapplied treatment can finish without an exception. Failure does not undo prior pro forma conversion.

```mermaid
stateDiagram-v2
  direction LR
  state "not created" as s0
  state "pending" as s1
  state "completed" as s2
  state "completed with exception" as s3
  state "failed" as s4
  s0 --> s2 : settle without delayed processor work
  s0 --> s1 : start settlement collection
  s1 --> s2 : finish successful collection
  s1 --> s4 : end unsuccessful settlement
  s1 --> s3 : retain a capture shortfall exception
```

## Transitions Explained

The transition rows identify the initiating action, eligibility checks, resulting records and responsible caller. They retain the pinned evidence for each path.

## What Cannot Happen

The invalid-transition rows describe final-state protection and unsupported paths; command eligibility remains distinct from the declared state vocabulary.

## Concurrency and Timing

Target resolution locks invoices in identity order and pending applications reserve credit. Completion caps applications and allocations at the balances then remaining. A pending settlement without an intent is eligible for failure after a day.