Split-Money Settlement

1. Overview — one fare, many payees

A RideChain delivery is paid for by one booker as a single Total Fare, but that money belongs to several parties the moment it lands: the partner(s) who carried the parcel, the RideChain Points that handled drop-off and collection, the Block Hub that consolidated a relay, and the platform itself. The job of split settlement is to fan that one amount out to all of them — without RideChain ever holding the money in between.

The split is executed by the gateway's native split rails, abstracted behind the same Go PaymentGateway interface used for pay-in:

Every booking obeys one balance identity. The Total Fare equals the sum of partner payouts, plus the sum of Point/Hub handling fees, plus the platform commission — and the platform commission is the slice that absorbs the gateway's processing fee and the tax reserve:

flowchart LR
  BK["📱 Booker pays Total Fare T
(one payment, in paise)"] --> ESC["Gateway escrow
(RideChain holds NO money)"]
  ESC --> SPL{"Split rail
Razorpay Route → Cashfree Easy Split"}
  SPL --> PA["🛵 Partner(s)
linked account / vendor"]
  SPL --> DP["🏪 Drop Point
handling fee"]
  SPL --> CP["🏪 Collect Point
handling fee"]
  SPL --> HB["🏬 Block Hub
(relay only)"]
  SPL --> PL["🏛️ Platform commission"]
  PL --> PG["PG fee ~2%"]
  PL --> TR["Tax reserve
(GST / TCS / TDS)"]
  PL --> NET["Net platform margin"]
  classDef store fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  classDef plat fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  class ESC store; class PL,PG,TR,NET plat;
        

2. The vendor / linked-account model

For money to reach a partner or Point directly, that party must first exist at the gateway as a payable entity: a Razorpay Route linked account or a Cashfree Easy Split vendor. Creating that entity requires a verified bank account / UPI handle and completed KYC — until then, no slice can be transferred to them.

Onboarding a payee is part of the partner/Point onboarding flow (see Onboarding & KYC) and standardises on Cashfree Easy KYC regardless of which rail later moves the money:

1. Collect identity & payout details — Aadhaar OKYC, PAN, and the payee's bank account or UPI handle, plus name/face match.
2. Penny-drop verification — a tiny credit confirms the bank/UPI actually belongs to the verified name before it is ever used for a payout.
3. Create the gateway entity — on success, a Route linked account (Razorpay) and/or an Easy Split vendor (Cashfree) is created and bound to the partner/Point record.
4. Mark payable — only now can the party appear as a split target. A split that names an un-onboarded payee holds that slice in escrow.

flowchart TB
  START["Partner / Point earns a slice"] --> Q{"Payee onboarded?
(linked account / vendor live)"}
  Q -->|"yes"| PAY["Transfer slice directly
(Route / Easy Split)"]
  Q -->|"no"| KYC{"KYC + penny-drop
complete?"}
  KYC -->|"not yet"| HOLD["HOLD slice in gateway escrow
(rest of split still releases)"]
  KYC -->|"now complete"| MAKE["Create linked account / vendor
mark payable"]
  MAKE --> PAY
  HOLD -. "KYC clears later" .-> MAKE
  classDef bad fill:#fdecea,stroke:#c0392b,color:#7b241c;
  classDef good fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
  class HOLD bad; class PAY good;
        

3. The split computation — worked example #1

Take the canonical single point-to-point booking with Total Fare ₹120 (12000 paise). One partner carries the parcel end to end; a drop Point and a collect Point each handle a physical handover; the platform takes the remainder, out of which it absorbs the gateway fee and the tax reserve.

The platform's ₹28 (2800 paise) is not all margin. It is the slice that quietly carries the cost of moving the money and the cost of tax:

pie showData title "₹120 booking split (paise)"
  "Partner 8000" : 8000
  "Drop Point 600" : 600
  "Collect Point 600" : 600
  "Platform 2800" : 2800
        

flowchart LR
  T["Total Fare ₹120
(12000 paise)"] --> S{"Split"}
  S -->|"8000"| P["🛵 Partner ₹80"]
  S -->|"600"| D["🏪 Drop Point ₹6"]
  S -->|"600"| C["🏪 Collect Point ₹6"]
  S -->|"2800"| PL["🏛️ Platform ₹28"]
  PL -->|"~240"| PG["PG fee ~₹2.4"]
  PL -->|"~300"| TX["Tax reserve ~₹3"]
  PL -->|"~2260"| NET["Net margin ~₹22.6"]
  classDef plat fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  class PL,PG,TX,NET plat;
        

4. Per-leg split for relay / milk-run — worked example #2

A relay (bundled milk-run) booking is multiple legs through a Block Hub, each leg a different partner. Money splits per leg, and each leg's slice releases when that leg's handover completes (dual-OTP + POD) — so the money chain advances in lockstep with the custody chain. Take the canonical relay with Total Fare ₹220 (22000 paise):

The key idea is lockstep: the partner who completes leg 1 is paid for leg 1 the moment the hub handover verifies — even though a second partner still has to finish the journey. The custody chain and the money chain advance together, link by link.

sequenceDiagram
  autonumber
  participant SB as "Sender / Drop Point"
  participant PA as "Partner A (leg 1)"
  participant HUB as "Block Hub"
  participant PB as "Partner B (leg 2)"
  participant CP as "Collect Point / Receiver"
  participant LED as "Escrow ledger"
  Note over SB,LED: "Escrow HOLD of 22000 paise at pay-in"
  SB->>PA: "Pickup OTP — leg 1 begins"
  PA->>HUB: "Handover at hub (dual-OTP + POD)"
  HUB-->>LED: "RELEASE_PARTNER A 5500 + RELEASE_HUB 800"
  HUB->>PB: "Leg 2 assigned"
  PB->>CP: "Drop (dual-OTP + POD)"
  CP-->>LED: "RELEASE_PARTNER B 9500 + RELEASE_POINT 600 + 600"
  Note over LED: "Delivery confirmed → COMMISSION 5000 (PG + tax reserve absorbed)"
        

5. The append-only escrow ledger

RideChain's money tables are immutable event logs. You never update a balance; you append a new, signed entry describing a movement. A party's balance is a projection — a fold over the entries — never a mutable counter. All amounts are stored as paise (integers); the ₹ figures are display only.

Here is the full ledger for the ₹120 single point-to-point booking once delivered and settled. Read top to bottom: one HOLD credit, then the slices released, then the platform's commission decomposed into PG fee + tax reserve + net. The entries sum to zero against the held amount — that is the reconciliation invariant.

Entries 5a–5c are sub-postings within the platform's 2800-paise commission, not new money out of the fare; they explain where the platform's slice goes (240 + 300 + 2260 = 2800). The relationship between bookings, legs and immutable ledger entries is a strict append-only event log:

erDiagram
  BOOKING ||--o{ LEG : "decomposes into"
  BOOKING ||--|| ESCROW_ACCOUNT : "holds fare"
  ESCROW_ACCOUNT ||--o{ LEDGER_ENTRY : "append-only log"
  LEG ||--o{ LEDGER_ENTRY : "triggers releases"
  PAYEE ||--o{ LEDGER_ENTRY : "credited by"
  BOOKING {
    string booking_id
    int total_fare_paise
    string status
  }
  LEG {
    string leg_id
    int seq
    string handover_state
  }
  LEDGER_ENTRY {
    string entry_id
    string type
    int amount_paise
    string idempotency_key
    datetime created_at
  }
  PAYEE {
    string payee_id
    string kind
    string linked_account_id
  }
        

6. Release timing & entry lifecycle

Money does not move on a clock — it moves on proof. Escrow is HOLD at pay-in; each leg's slice is RELEASEd on that leg's handover (dual-OTP + POD); the booking reaches SETTLED on final delivery + POD, at which point the platform commission books. Payout to the partner's UPI / bank is then instant or daily depending on rail and partner tier.

1. HOLD at pay-in — the full Total Fare is captured into gateway escrow; the ledger appends one HOLD credit.
2. RELEASE per leg — each completed handover (dual-OTP + geo/time POD) appends the RELEASE_* entries that leg has earned and instructs the split rail to transfer them.
3. SETTLED on final delivery — the last drop's OTP + POD closes the booking; COMMISSION (with PG_FEE + TAX_RESERVE) books and the escrow balance returns to zero.
4. Payout — the released slices land in each payee's account via Route / Easy Split / Payouts: instant for trusted partners, daily-batched otherwise.

stateDiagram-v2
  [*] --> HELD
  HELD --> RELEASED: "leg handover verified (dual-OTP + POD)"
  HELD --> REFUND_DUE: "leg fails / cancel before release"
  RELEASED --> PAID_OUT: "Route / Easy Split transfer (instant or daily)"
  RELEASED --> REVERSED: "dispute resolved for booker"
  REFUND_DUE --> REFUNDED: "gateway refund webhook"
  PAID_OUT --> [*]
  REFUNDED --> [*]
  REVERSED --> REFUNDED
        

7. Reconciliation & payout failures

Because the ledger is a mirror of gateway activity, the two must agree to the paise. A daily reconciliation job pulls each gateway's settlement / payout report and diffs it against the internal append-only ledger. Matches are marked reconciled; missing webhooks are recovered by replaying the idempotent transition; genuinely unexplained gaps are flagged and the affected booking's further releases are frozen until ops clears it.

flowchart TB
  CRON["Daily reconciliation job"] --> PULL["Pull gateway settlement + payout report
(Razorpay Route / Cashfree)"]
  PULL --> DIFF{"Diff vs append-only ledger
(paise-exact)"}
  DIFF -->|"match"| OK["Mark reconciled"]
  DIFF -->|"missing webhook"| REPLAY["Replay idempotent entry
(no double-apply)"]
  DIFF -->|"payout failed"| RETRY{"Retry payout"}
  DIFF -->|"unexplained mismatch"| FREEZE["Flag + freeze further releases
(ops review)"]
  RETRY -->|"ok"| OK
  RETRY -->|"still failing"| FALLBACK["Fallback rail / wallet
+ notify payee"]
  REPLAY --> OK
  classDef bad fill:#fdecea,stroke:#c0392b,color:#7b241c;
  class FREEZE,FALLBACK bad;
        

Payout failures (a closed UPI handle, a bounced bank credit) are first-class: the failed transfer is retried, then routed to the fallback rail or held to the payee's RideChain Wallet, and the payee is notified — the released slice is never lost, only delayed. A persistent failure surfaces in the ops queue with the exact ledger entry it relates to.

8. Tax & statements

Settlement produces the paper trail that keeps everyone honest and compliant. Tax is computed against the captured fare; the tax reserve is held out of the platform's commission slice (the ~₹3 / 300 paise in the ₹120 example), so partners and Points always receive their stated payout in full.

9. Edge cases & failure modes

Split settlement assumes payees will be half-onboarded, UPIs will be closed, relays will fail mid-way and gateways will flake. Every money-touching failure has a defined, idempotent mitigation; the full catalogue lives in the Edge-Case Catalog.