---
id: STATE-ACC-REC-002
title: Payout bank verification
object: DOM-ACC-REC-001
product_area: accounting
module: reconciliation
revision: 3
status: draft
design_intent: proposed
implementation_evidence: inconsistent
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: unverified
    meaning: The payout has no recorded bank outcome yet.
  - name: verified
    meaning: Recorded bank agreement supplies the accounting day.
  - name: mismatch
    meaning: Recorded disagreement retains a bank-mismatch warning.
transitions:
  - from: unverified
    to: verified
    trigger: Record bank agreement.
    guard: >-
      Evidence, bank day, outcome, key and current version are valid; stated
      amount agrees and the payout is neither void nor approved-held.
    side_effects:
      - >-
        Retain evidence, verifier and time; use the posted bank day and record
        activity.
    who: Authorized bank verifier
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/payouts.ts:verifyPayoutBank
  - from: unverified
    to: mismatch
    trigger: Record bank disagreement.
    guard: Verification inputs are valid and any stated bank amount differs.
    side_effects:
      - >-
        Retain the bank outcome and raise one informative mismatch warning; use
        the reported or funding accounting day.
    who: Authorized bank verifier
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/bank-mismatch-exceptions.ts
  - from: mismatch
    to: verified
    trigger: Record later bank agreement.
    guard: >-
      The payout remains eligible for verification with complete evidence and
      current version.
    side_effects:
      - Close the active mismatch warning and adopt the bank posting day.
    who: Authorized bank verifier
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/payouts.ts:verifyPayoutBank
  - from: verified
    to: mismatch
    trigger: Replace agreement with new disagreement.
    guard: >-
      Complete mismatching evidence is supplied before approval seals the
      payout.
    side_effects:
      - >-
        Raise or reopen the mismatch warning and return accounting to the
        reported or funding day.
    who: Authorized bank verifier
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/payouts.ts:verifyPayoutBank
invalid:
  - from: verified
    to: unverified
    why: No command returns recorded verification to an unverified outcome.
  - from: mismatch
    to: unverified
    why: >-
      Mismatch can be replaced by evidence of agreement, but cannot be cleared
      to unverified.
concurrency: >-
  Verification locks the holder and payout, compares the expected version and
  replays retained keyed results. Its version increment makes a later command
  using the earlier version stale.
invariants:
  - INV-DOM-ACC-REC-001-06
  - INV-DOM-ACC-REC-001-08
evidence:
  - >-
    services-accounting at f47cb263:
    modules/reconciliation/services/persistence/payouts.ts,
    bank-mismatch-exceptions.ts; aws/api/payouts.schemas.ts;
    db/payouts.table.ts; docs/reconciliation/architecture.md §14.1.
  - >-
    react-console at baf6dae3: lib/accounting/reconciliation/client.ts
    (verifyBank sends only the version), store.tsx;
    components/accounting/reconciliation/workspace/workspace.tsx.
---
# Payout bank verification

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> unverified : payout recorded
  unverified --> verified : bank agrees
  unverified --> mismatch : bank disagrees
  mismatch --> verified : bank later agrees
  verified --> mismatch : new evidence disagrees
```

## Transitions Explained

Bank evidence records agreement or disagreement independently of reconciliation. Agreement adopts the bank posting day; disagreement uses the reported or funding day and retains a warning.

## What Cannot Happen

The service refuses verification after cancellation or approved holding. The console currently submits an incomplete verification request and therefore cannot complete this control.

## Concurrency and Timing

Verification locks the holder and payout, compares the expected version and replays retained keyed results. Its version increment makes a later command using the earlier version stale.