📂 Fail MD
📄 api-spec.md
📄 architecture.md
📄 compound-rules.md
📄 council-sync.md
📄 data-model.md
📄 money-ledger.md
📄 parking-rules.md
Sedang mengedit: money-ledger.md
# Smart Parking — Money & Ledger How money flows physically vs logically, and how every cent is traced. ## Core Principle > Physical money sits pooled in **Company A's single bank account**. The split between liability, revenue, commission, and reserve is purely **logical (ledger)**. Physical money only moves on **top-up/payment in** and **settlement/refund out**. ``` User pays / tops up │ via gateway (Razer / Chip Asia) — gateway fee deducted ▼ Company A bank account (all funds pooled — bank doesn't know the split) │ │ logical split tracked in ledger: ├─ Liability (wallet float — user's money, not revenue) ├─ Recognized revenue (spent on parking/compound) │ ├─ Commission (Company A, per-tenant rate) │ ├─ Reserve (rolling, held back) │ └─ Net payable to council └─ ... ``` ## Two Separate Pools (never mix) ``` ┌──────────────────────────────────────────────────────┐ │ WALLET FLOAT / LIABILITY │ │ = top-up not yet spent │ │ = user's money (Company A owes the user) │ │ = NOT anyone's revenue │ │ = stays in account, carried forward month to month │ │ = does NOT leave during settlement │ └──────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────┐ │ RECOGNIZED REVENUE │ │ = money actually spent (parking / compound) │ │ ├─ gateway fee (deducted first) │ │ ├─ Company A commission (per tenant) │ │ ├─ reserve held (rolling) │ │ └─ net payout to council │ └──────────────────────────────────────────────────────┘ ``` ## Payment Methods - **E-Wallet:** user tops up balance (liability). Spending converts liability → revenue. Wallet is **global** (no tenant); the spend's `tenant_id` is set by parking/compound location. - **Direct (FPX / Card / saved card):** charged at point of use; goes straight to recognized revenue for that tenant. Never touches wallet. ## Ledger (Immutable) Every movement is one append-only entry. Balances are **computed** from the ledger, never stored as a mutable number. | Type | Sign | tenant_id | Meaning | |---|---|---|---| | `TOPUP` | + | none | Wallet top-up (liability) | | `GATEWAY_FEE` | - | (context) | Fee charged by Razer/Chip Asia | | `PAYMENT_PARK` | - (wallet) / + (rev) | tenant | Parking paid (recognized revenue) | | `PAYMENT_COMPOUND` | - (wallet) / + (rev) | tenant | Compound paid | | `COMMISSION` | - | tenant | Company A share | | `RESERVE_HOLD` | - | tenant | Held back from payout | | `RESERVE_RELEASE` | + | tenant | Reserve released when unused | | `PAYOUT` | - | tenant | Transfer to council bank | | `REFUND` | - | none | Wallet balance returned to user | Example trail: ``` | type | amount | tenant | reference | |------------------|--------|--------|------------------| | TOPUP | +50.00 | - | razer:abc123 | | PAYMENT_PARK | -2.00 | MBPP | session:5566 | | PAYMENT_COMPOUND | -30.00| MBSP | compound:7788 | | COMMISSION | -X | MBPP | statement:0625 | | RESERVE_HOLD | -100k | - | reserve:0625 | | PAYOUT | -550k | MBPP | settle:0625-PP | | RESERVE_RELEASE | +X | MBPP | reserve:0625-rel | | REFUND | -8.00 | - | refund:U123 | ``` ## Refunds - Only the **current E-Wallet balance** is refundable (it's the user's money). - **Parking time is non-refundable:** pay 6h = 6h, even if only 1h is used. - Refund is paid from the **liability pool**. ## Reserve (Rolling) - A portion of the council's share is **held back** each period (example: RM100k) to cover refunds/chargebacks. - Not distributed; **carried to next month**. - **Released** to the council when unused; **drawn down** if refunds/chargebacks occur. - Mirrors a payment aggregator's rolling reserve. ## Settlement - Process of transferring each council's **recognized, net share** from Company A's account to the council's bank account. - Timing follows the **gateway schedule** (T+1, or live transaction — depends on the gateway/method). - Settlement is based on **recognized revenue only** — never on raw bank balance (which includes liability). ``` Per period, per tenant: gross revenue (recognized) - gateway fees - commission (tenant rate) - reserve held + reserve released (from prior period, if any) ───────────────────────────── = net payout → transfer to council ``` ## Reconciliation At any time the following must hold: ``` bank balance = liability (wallet float) + reserve (held, not released) + unsettled recognized revenue + unreleased commission ``` Difference should be **0**. A non-zero difference signals missing/duplicated money movement. ## Monthly Float Movement (carry-forward) ``` Opening float (from last month) : RM A (+) New top-ups this month : RM B (-) Spent (became revenue) this month : RM C (-) Refunds to users : RM D ───────────────────────────────────────────── Closing float (carried to next month) : RM (A+B-C-D) ``` ## Multi-Tenant Visibility - **One ledger**, filtered views by role + tenant. - **MBPP / MBSP:** see only their recognized revenue, their compounds, their settlement. Wallet float shown as **info only** (labelled "not your revenue"). - **Company A:** sees everything — full float, commission, reserve, reconciliation, all tenants.
Simpan Perubahan