# Commercial file, bookings & payments (Phase 04)

A quote, pre-booking, confirmed booking and completed trip are the **same
record** (`bookings`) evolving under one folio. Documents (receipts, statements)
are derived representations, never a parallel commercial record.

## Four independent states

`commercial_status` (draft/quoted/pre_reserved/confirmed/cancelled/transferred/
completed/expired), `financial_status`, `documentary_status` and
`operational_status` move independently. The financial status is recomputed from
the ledger; the others are set by their own flows.

## The ledger is the source of truth

The receivable **balance is derived**, never stored as an editable number:

```
balance = Σ booking_charges.signed_amount  −  (Σ applied payments.base_amount − Σ refunds.base_amount)
```

Charges/penalties are positive; discounts/credits negative. All money math uses
**bcmath at 2 decimals** with explicit half-up rounding (`Money`) — never floats.

## Payments are immutable

`PaymentService::register` locks the booking, converts the amount to the booking
currency at the applied exchange rate, **refuses over-payment** unless
authorized, assigns a unique folio, records `previous_balance`/`resulting_balance`,
writes allocations (whole booking or per passenger), applies the amount to the
oldest-due installment, and issues a **receipt + statement snapshot + timeline
event**. It is **idempotent** via the `Idempotency-Key` header. Corrections never
edit a payment: a **reversal** flags it and a **refund** is a separate movement,
so the balance recomputes on its own.

## Multicurrency

Each amount keeps its ISO currency, exchange rate and base-currency equivalent.
Editing today's rate never rewrites historical movements.

## Financing

`payment_plans` + `installments` are configurable; installment status
(pending/partial/paid/overdue/waived) is **derived** from paid amount and due
date. We model surcharge/discount, never regulated "interest".

## Cancellation & transfer

Cancellation never deletes: it credits the prior sale down to the agreed
penalty, optionally refunds the favour, and marks the state cancelled with a
timeline event. Balance transfers move a favour between bookings.

## API (`/api/v1/tenant`, Sanctum + brand + permissions)

`GET/POST /bookings`, `GET /bookings/{uuid}`, `POST /bookings/{uuid}/confirm`,
`POST /bookings/{uuid}/payments` (permission `payments.register`,
`Idempotency-Key` header), `POST /payments/{uuid}/reverse` (`payments.void`).
Client documents never show supplier costs.