# IncomingPayment

## Description

IncomingPayment is the AR-owned payment document that records a payment amount for one customer, company, and currency. A DRAFT payment is editable together with its AccountReceivableSettlement rows. Posting validates the selected AR 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: createIncomingPayment
    DRAFT --> DRAFT: updateIncomingPayment
    DRAFT --> POSTED: postIncomingPayment
    DRAFT --> CANCELLED: cancelIncomingPayment
    POSTED --> REVERSED: reverseIncomingPayment
    CANCELLED --> [*]
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| update | DRAFT | DRAFT | [updateIncomingPayment](../command/UpdateIncomingPayment.md) |
| post | DRAFT | POSTED | [postIncomingPayment](../command/PostIncomingPayment.md) |
| cancel | DRAFT | CANCELLED | [cancelIncomingPayment](../command/CancelIncomingPayment.md) |
| reverse | POSTED | REVERSED | [reverseIncomingPayment](../command/ReverseIncomingPayment.md) |

### Command Definitions

- [createIncomingPayment](../command/CreateIncomingPayment.md) - Create a DRAFT payment with optional initial settlements
- [updateIncomingPayment](../command/UpdateIncomingPayment.md) - Update a DRAFT payment and incrementally add, update, or remove settlements
- [postIncomingPayment](../command/PostIncomingPayment.md) - Validate and post a DRAFT payment with its journal entry
- [cancelIncomingPayment](../command/CancelIncomingPayment.md) - Cancel a DRAFT payment without accounting effect
- [reverseIncomingPayment](../command/ReverseIncomingPayment.md) - Mark a POSTED payment REVERSED and create reversing settlements

### Query Definitions

- [getIncomingPayment](../query/GetIncomingPayment.md) - Return payment facts for downstream reconciliation

### Models

- IncomingPayment
- AccountReceivableSettlement

### Invariants

- An IncomingPayment belongs to exactly one company, customer CustomerAccount, and currency
- At creation and posting, the CustomerAccount belongs to the payment company and is available for transactions
- `companyId`, `customerAccountId`, 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 IncomingPayment id
- Normal payment accounting credits receivable control accounts for invoice settlements, debits receivable control accounts for credit memo settlements, and debits `paymentAccountId` by the net total
- Reversal updates the original payment header from POSTED to REVERSED; it never creates another IncomingPayment
- 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 CustomerAccount**: Each payment references one customer through `customerAccountId`
- **References Currency**: Each payment uses one transaction currency through `currencyId`
- **References Account**: Each payment debits `paymentAccountId` when posted; its reversal journal credits the same account
- **Has Many AccountReceivableSettlement**: A payment owns its due-schedule allocations