Finance
Tables and relationships for the finance domain.
Part of the data model; conventions and base columns are documented there.
ledger_accounts (Base +): owner_type_id FK lookups (ledger_owner: platform, organization, supplier, traveler_clearing, gateway), organization_id NULL, user_id NULL, account_kind_id FK lookups (ledger_account_kind: cash, receivable, payable, revenue, commission, fee_expense, deferred, refund_clearing, tax_payable), currency_code, code VARCHAR(60) unique.
ledger_transactions (immutable) FR-ACC-01: id, uuid, event_type_id FK lookups (ledger_event: booking_paid, refund, coupon, deal_cost, commission, gateway_fee, plan_charge, payout, invoice, settlement, reversal), source_type VARCHAR(40), source_id BIGINT, occurred_at, reverses_transaction_id FK NULL, created_at, created_by. A check confirms entries sum to zero per currency.
ledger_entries (immutable): id, uuid, transaction_id FK, account_id FK, organization_id NULL, debit_minor BIGINT, credit_minor BIGINT (one is zero), currency_code, trip_id NULL, booking_id NULL, deal_id NULL, gateway_reference NULL, created_at, created_by. Retention 7 years.
invoices
| Column | Type | Notes |
|---|---|---|
| organization_id | BIGINT NULL | Issuer when the organization invoices a traveler; null for platform-issued |
| issuer_type_id | BIGINT FK lookups | invoice_issuer: organization, platform, supplier |
| buyer_type_id | BIGINT FK lookups | invoice_buyer: traveler, organization, supplier |
| kind_id | BIGINT FK lookups | invoice_kind: b2c, b2b, credit_note |
| number | VARCHAR(40) | Unique per issuer and market; null while numbering is retried (D-179) |
| market_id | BIGINT FK markets | |
| buyer_name, buyer_tax_no, buyer_address | VARCHAR, VARCHAR, JSONB | |
| booking_id, subscription_charge_id, deal_id, settlement_id | BIGINT NULL | Source |
| original_invoice_id | BIGINT FK invoices NULL | For credit notes (BRL-28) |
| subtotal_minor, tax_minor, total_minor | BIGINT | |
| currency_code | CHAR(3) | |
| status_id | BIGINT FK lookups | invoice_status: pending_number, issued, voided_by_credit, finance_review |
| issued_at | TIMESTAMPTZ | |
| e_invoice_status_id | BIGINT FK lookups NULL | Reserved for ZATCA (OD-10) |
| pdf_path | TEXT |
invoice_lines (Base +): invoice_id FK, description JSONB, quantity NUMERIC(10,2), unit_minor BIGINT, tax_rate_bp INT, tax_minor BIGINT, line_total_minor BIGINT.
payout_runs (Base +) FR-ACC-03: run_date DATE (Mondays 06:00, D-28), market_id FK, status_id FK lookups (payout_run_status: draft, approved, submitted, completed, partial), approved_by FK users.
payouts (Base +): payout_run_id FK, payee_user_id FK NULL, payee_organization_id FK NULL, payout_method_id FK, amount_minor, currency_code, status_id FK lookups (payout_status: pending, sent, paid, failed, held), hold_reason_id FK lookups NULL (lab pause D-175, negative balance D-173), external_reference VARCHAR(120), paid_at.
settlements (Base +) FR-ACC-05, BRL-25: organization_id, trip_id FK UNIQUE, status_id FK lookups (settlement_status: open, awaiting_payouts, disputed, closed), opened_at (trip Completed), closed_at, totals JSONB (gross, commission, fees, supplier costs, net).
settlement_lines (Base +): settlement_id FK, from_party_type_id FK lookups (party), from_party_id BIGINT, to_party_type_id FK lookups (party), to_party_id BIGINT, reason_id FK lookups (settlement_reason: trip_revenue, commission, deal_cost, gateway_fee, refund, adjustment), amount_minor, currency_code, payout_id FK NULL, settled_at.
reconciliation_exceptions (Base +) FR-PAY-05: gateway_id FK lookups, report_date DATE, gateway_reference VARCHAR(120), kind_id FK lookups (recon_exception: missing_in_ledger, missing_in_gateway, amount_mismatch, currency_mismatch), gateway_amount_minor, ledger_amount_minor, status_id FK lookups (exception_status: open, resolved, written_off), resolved_by FK users NULL.
disputes (Base +) FR-ADM-04, FR-ADM-08: organization_id NULL, booking_id FK NULL, deal_id FK NULL, raised_by FK users, type_id FK lookups (dispute_type: booking, payment, refund, supplier_conduct, organization_conduct, other), status_id FK lookups (dispute_status: open, information_requested, under_review, resolved, closed), ack_due_at (2 working days), resolve_due_at (10 working days), outcome TEXT, refund_id FK refunds NULL, assigned_to FK users NULL.
dispute_files (Base +): dispute_id FK, storage_path TEXT, size_bytes BIGINT (up to 5 files of 10 MB, D-259).