---
id: STATE-ACC-TRX-009
title: Remittance
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: The group receipt has not been recorded.
  - name: recorded
    meaning: Member receipts and any remitter remainder have been created.
  - name: voided
    meaning: The associated receipts have been cancelled and debt restored.
transitions:
  - from: not created
    to: recorded
    trigger: record a group receipt
    guard: >-
      An offline method, up to 250 eligible member lines and matching customer,
      unit and currency are required; total must reconcile with lines and
      explicit remainder.
    side_effects:
      - create keyed member receipts
      - retain the remitter remainder as unapplied money
      - save the remittance and its history
    who: >-
      Staff with both remittance-create and payment-create permission through
      the API.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/remittances/remittance-commands.ts;
      services-accounting:modules/transactions/db/remittances.table.ts;
      services-accounting:modules/transactions/tests/integration/services/remittances/record-remittance.integration.spec.js#it
      allocates each member’s payment wholly to that member’s invoice, and
      leaves the remainder unapplied on Metro Transit
  - from: recorded
    to: voided
    trigger: cancel a group receipt
    guard: >-
      A reason is required and its receipts must remain unposted and unused
      beyond their original allocations.
    side_effects:
      - cancel the associated live receipts
      - restore invoice debt
    who: Staff with both remittance-void and payment-void permission.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/remittances/remittance-commands.ts;
      services-accounting:modules/transactions/db/remittances.table.ts;
      services-accounting:modules/transactions/tests/integration/services/remittances/void-remittance.integration.spec.js#it
      voids every payment it made, taking their allocations back and returning
      the remainder
invalid:
  - from: voided
    to: recorded
    why: A cancelled group receipt does not return to recorded status.
  - from: recorded
    to: recorded
    why: >-
      Correction creates replacement history through cancellation and a new
      remittance.
concurrency: >-
  Invoice locking follows identity order, and member payments use keys derived
  from the group request to avoid recording receipt money twice.
invariants:
  - INV-DOM-ACC-TRX-003-17
evidence:
  - >-
    services-accounting at f47cb263:
    services/remittances/remittance-commands.ts, remittance-rules.ts;
    db/remittances.table.ts.
---
# Remittance

## The Lifecycle

A remittance groups separately owned customer receipts. Whole-group cancellation checks their current use before changing any member.

```mermaid
stateDiagram-v2
  direction LR
  state "not created" as s0
  state "recorded" as s1
  state "voided" as s2
  s0 --> s1 : record a group receipt
  s1 --> s2 : cancel a group receipt
```

## 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

Invoice locking follows identity order, and member payments use keys derived from the group request to avoid recording receipt money twice. The workflow is synchronous and has no dedicated console entry screen.