# Payables Settlement Foundation v28

## Purpose

v28 adds supplier payment settlement on top of Accounts Payable.

Lifecycle:

Approved Supplier Invoice
→ Open Payable
→ Partial Supplier Payment(s)
→ Paid Payable

## Payments

A supplier payment stores:
- supplier
- payment number
- currency
- total payment amount
- payment method
- external/reference number
- payment date
- occurred_at
- idempotency key

Supported methods:
- cash
- bank_transfer
- cheque
- external

## Allocation

A single supplier payment may allocate to one or more open payables for the same supplier
and currency.

A payment cannot:
- exceed payable outstanding balance
- mix suppliers
- mix currencies

## Payable state

After allocation:

outstanding =
previous outstanding - allocated amount

Status:
- open
- partial
- paid

When outstanding reaches zero:
- status = paid
- settled_at is captured

## Payables ledger

`payables.ledger_entries` is an immutable signed liability ledger.

Initial entry types:
- invoice_open
- payment_apply
- payment_reversal
- adjustment

Convention:
- invoice_open = positive liability
- payment_apply = negative liability

v28 backfills existing approved AP records as `invoice_open` entries.

The operational `accounts_payable.outstanding_amount` remains a fast balance projection.

## Idempotency

`payables.payments` has tenant-scoped idempotency.

Retrying the same supplier payment returns the original payment and does not allocate twice.

## API

POST /api/v1/payables/payments

Existing:
GET /api/v1/payables

## Permissions

- payables.view
- payables.pay

## Next

v29:
- payable payment reversal
- controlled correction flow
- cash/bank account source model
- cash movement integration