How Neo records money

Settlement policy

Immutable policy platform-collected-ngn-v1 supports NGN platform-collected settlement. The merchant owns merchandise proceeds after seller-funded discounts and creator commission. The creator owns attributed commission. The courier owns the delivery fee. Neo owns service revenue and bears PSP charges.

Values are integer minor units. Percentage commission rounds down. Non-zero tax and unsupported currency fail closed. Policy changes require a new version rather than mutation.

Capture allocation

flowchart LR
  Capture[Buyer captured total] --> Clearing[Provider clearing asset]
  Capture --> Merchant[Merchant held payable]
  Capture --> Creator[Creator held payable]
  Capture --> Courier[Courier payable]
  Capture --> Neo[Neo revenue]
  PSP[PSP charge] --> NeoCost[Neo expense]
  Complete[Completed order] --> Available[Merchant and creator available payables]

Every captured minor unit is assigned exactly once. Payment confirmation and its capture journal commit atomically. Completion reclassifies eligible merchant and creator ownership from held to available; a hold changes availability, not ownership.

Ledger model

Currency-scoped accounts carry owner type, owner ID, account class, and purpose. A journal header has a unique source and idempotency key, policy version, optional reversal link, and immutable metadata. Entries carry debit or credit direction and must balance per currency before commit.

Database triggers reject updates and deletes. Corrections use an explicit reversing journal. Changed replay of an existing idempotency key is rejected.

Balances and limitations

Payout rows derive from funded available ledger balances, not the gross payment. Disputes, refunds, risk, reserves, and financial divergence can hold availability. Provider-confirmed transfers post a separate journal.

The ledger being implemented, tested, or deployed does not mean live payouts or refunds are enabled. Money movement also requires a verified recipient, exact provider evidence, kill-switch enablement, certification, and clear reconciliation state.

• src/finance/settlement-policy.ts
• src/finance/ledger.ts
• db/migrations/032_financial_ledger.sql
• test/settlement-policy.test.ts
• test/financial-ledger.test.ts