# OutgoingPayment

## Description

OutgoingPayment is the AP-owned payment document that records a payment amount for one supplier, company, and currency. A DRAFT payment is editable together with its AccountPayableSettlement rows. Posting validates the selected AP due schedule lines, prevents cumulative over-settlement, posts a balanced journal entry directly in financial-accounting, and makes the payment immutable. Cancellation is available only before posting. Reversal changes the same payment header from POSTED to REVERSED, adds linked reversing settlement rows, and posts the opposite accounting entry.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> DRAFT: createOutgoingPayment
    DRAFT --> DRAFT: updateOutgoingPayment
    DRAFT --> POSTED: postOutgoingPayment
    DRAFT --> CANCELLED: cancelOutgoingPayment
    POSTED --> REVERSED: reverseOutgoingPayment
    CANCELLED --> [*]
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| update | DRAFT | DRAFT | [updateOutgoingPayment](../command/UpdateOutgoingPayment.md) |
| post | DRAFT | POSTED | [postOutgoingPayment](../command/PostOutgoingPayment.md) |
| cancel | DRAFT | CANCELLED | [cancelOutgoingPayment](../command/CancelOutgoingPayment.md) |
| reverse | POSTED | REVERSED | [reverseOutgoingPayment](../command/ReverseOutgoingPayment.md) |

### Command Definitions

- [createOutgoingPayment](../command/CreateOutgoingPayment.md) - Create a DRAFT payment with optional initial settlements
- [updateOutgoingPayment](../command/UpdateOutgoingPayment.md) - Update a DRAFT payment and incrementally add, update, or remove settlements
- [postOutgoingPayment](../command/PostOutgoingPayment.md) - Validate and post a DRAFT payment with its journal entry
- [cancelOutgoingPayment](../command/CancelOutgoingPayment.md) - Cancel a DRAFT payment without accounting effect
- [reverseOutgoingPayment](../command/ReverseOutgoingPayment.md) - Mark a POSTED payment REVERSED and create reversing settlements

### Query Definitions

- [getOutgoingPayment](../query/GetOutgoingPayment.md) - Return payment facts for downstream reconciliation

### Models

- OutgoingPayment
- AccountPayableSettlement

### Invariants

- An OutgoingPayment belongs to exactly one company, supplier SupplierAccount, and currency
- At creation and posting, the SupplierAccount belongs to the payment company and is available for transactions
- `companyId`, `supplierAccountId`, and `currencyId` are fixed when the payment is created
- A payment has a positive `totalAmount` and references an ACTIVE company-scoped payment account
- A payment is created in DRAFT status
- Only DRAFT payments and their settlements are editable
- Only DRAFT payments can be cancelled or posted
- A POSTED payment is immutable and records `postedAt`
- A REVERSED payment retains its original payment identity, amount, payment date, and `postedAt`, and records `reversalDate` and `reversedAt`
- A CANCELLED payment has no accounting or settlement effect and records `cancelledAt`
- A DRAFT payment may have no settlements while it is being prepared
- A payment must have at least one settlement before posting
- For a POSTED payment, settlement amounts remain positive and their due-schedule-directed signed total equals `totalAmount`
- Posting and reversal each post one journal entry whose source document id is the created or posted OutgoingPayment id
- Normal payment accounting debits payable control accounts for invoice settlements, credits payable control accounts for credit memo settlements, and credits `paymentAccountId` by the net total
- Reversal updates the original payment header from POSTED to REVERSED; it never creates another OutgoingPayment
- Reversal creates one reversing settlement for each original settlement under the same payment and links it through `reversalOfSettlementId`
- A payment can be reversed at most once
- Reversal accounting is the exact opposite of the original payment accounting

### Relationships

- **References Company**: Each payment is scoped to a Company through `companyId`
- **References SupplierAccount**: Each payment references one supplier through `supplierAccountId`
- **References Currency**: Each payment uses one transaction currency through `currencyId`
- **References Account**: Each payment credits `paymentAccountId` when posted; its reversal journal debits the same account
- **Has Many AccountPayableSettlement**: A payment owns its due-schedule allocations