Onboarding & KYC

1. Overview — three onboarding tracks

Onboarding is where RideChain earns the right to put a stranger in custody of someone else's parcel and someone else's money. There are three distinct tracks, each with a different friction budget because each carries a different risk. The hardest, most thorough track is the Delivery Partner — and that is deliberate, because partner trust is the number-one fraud lever in the whole system. A weak partner KYC poisons every later control (custody chain, escrow release, COD handling); a strong one makes most downstream fraud uneconomic.

flowchart TB
  START["📱 New user opens app
or walks into a Point"] --> Q{"Which role?"}
  Q -- "I want to deliver" --> A["🛵 Track A · Delivery Partner
full KYC + vehicle + vouch + quiz + bg-check"]
  Q -- "I want to send a parcel" --> B["📦 Track B · Booker
phone + OTP + language only"]
  Q -- "I run a shop" --> C["🏪 Track C · RideChain Point
shop KYC + geo + hours + capacity"]
  A --> AG["Graduated activation
(New → Bronze → … → Platinum)"]
  B --> BK["Can book immediately;
KYC-lite only if high value / COD"]
  C --> PT["Scanner-lite app + signboard
+ per-parcel commission"]
  classDef a fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  classDef b fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  classDef c fill:#e9f7ef,stroke:#1e8e4e,color:#13602f;
  class A,AG a; class B,BK b; class C,PT c;
        

2. Partner onboarding — the full sequence

Partner onboarding is a linear pipeline of trust gates. Each gate is independently re-runnable and idempotent (so a dropped signal mid-flow never loses progress), and a partner can resume exactly where they left off. The order is chosen so the cheapest, highest-signal checks run first, and the slow ones (background check) run last in parallel with a limited "prepaid low-value" head start.

flowchart TB
  P0["📞 Phone + OTP + language"] --> P1["🪪 Identity · Cashfree Easy KYC
(Aadhaar OKYC — store masked token, never raw)"]
  P1 --> P2["🤳 Liveness + face match
(deepfake-resistant)"]
  P2 --> P3{"Vehicle type?"}
  P3 -- "cycle / cart" --> P5["📷 Capacity profile
(max weight/size, vehicle photos,
service radius, availability,
which Points served)"]
  P3 -- "motorized" --> P4["🚗 Vehicle registration
RC via VAHAN · DL via Sarathi"]
  P4 --> P5
  P5 --> P6["🏦 Bank / UPI payout setup
penny-drop name match"]
  P6 --> P7["🤝 Community / panchayat vouch"]
  P7 --> P8["🎓 5-min safety micro-training + quiz"]
  P8 --> P9["🔎 Tiered background check"]
  P9 --> P10["✅ Graduated activation
(start as New tier)"]
  classDef g fill:#e9f7ef,stroke:#1e8e4e,color:#13602f;
  class P10 g;
        

1. Phone + OTP + language — the entry. Pick a vernacular (Hindi-first); the whole flow is then voice-guided in that language.
2. Identity via Cashfree Easy KYC — Aadhaar OKYC (OTP to the Aadhaar-linked number). We store only a masked token + verification status, never the raw Aadhaar number.
3. Liveness + face match — a short active-liveness check (blink / turn) matched against the OKYC photo, hardened against printed photos, screen replays and deepfake video.
4. Vehicle registration — choose vehicle type; for motorized vehicles the RC is validated via VAHAN and the DL via Sarathi. Cycle / cart skip DL/RC (no such document) but still complete identity + face match.
5. Capacity profile — max weight & size bucket, vehicle photos, service radius, availability windows, and which RideChain Points they serve. This feeds the matching engine directly.
6. Bank / UPI payout setup — a penny-drop credits ₹1 and reads back the account-holder name, which must match the KYC name before payouts are enabled (platform holds no money; payouts flow via Razorpay Route / Cashfree Easy Split).
7. Community / panchayat vouch — an existing partner, Point operator or panchayat reference vouches; raises starting trust and is itself a fraud signal if abused.
8. 5-min safety micro-training + quiz — short vernacular video + handling rules (fragile, perishable, OTP discipline, COD honesty) with a pass-gate quiz.
9. Tiered background check — depth scales with what the partner will be trusted to carry (low-value prepaid vs high-value / COD / long-haul). May run in the background.
10. Graduated activation — the partner goes live at the New tier with the most conservative limits and climbs from there (see §4).

3. Cashfree Easy KYC integration

All identity and bank verification goes through Cashfree Easy KYC (no DigiLocker in MVP). The app never talks to Cashfree directly — it calls the Go auth module, which orchestrates the calls, stores only tokenized results, and is the single place where DPDP obligations are enforced.

sequenceDiagram
  autonumber
  participant APP as "Partner app (Flutter)"
  participant GO as "Go auth module"
  participant CF as "Cashfree Easy KYC"
  participant DB as "Postgres (tokenized)"
  APP->>GO: "Start KYC (consent captured)"
  GO->>CF: "Aadhaar OKYC — send OTP to Aadhaar-linked phone"
  CF-->>APP: "OTP delivered"
  APP->>GO: "Submit OKYC OTP"
  GO->>CF: "Verify OKYC OTP"
  CF-->>GO: "OKYC result + masked Aadhaar + photo (no raw number)"
  GO->>CF: "PAN verify (where required)"
  CF-->>GO: "PAN name + status"
  GO->>CF: "Liveness + face match vs OKYC photo"
  CF-->>GO: "Match score + liveness pass/fail"
  GO->>CF: "Bank / UPI penny-drop (₹1)"
  CF-->>GO: "Account-holder name + verified"
  GO->>GO: "Name match: KYC name == bank name?"
  GO->>DB: "Store masked token + verification status only"
  GO-->>APP: "KYC complete / step failed (reason)"
        

Not every check applies to every partner. The partner class (what they will be trusted to carry) decides the depth of verification — a cycle courier carrying ₹100 prepaid parcels does not need the same checks as a Tata Ace driver handling high-value COD.

4. Graduated trust tiers

Onboarding does not end at activation — it graduates. A newly verified partner starts at New with the most conservative limits and climbs as they accumulate clean signals. This is the bridge between onboarding and fraud control: even a fully KYC'd partner cannot carry a ₹40,000 high-value parcel on day one. Trust is earned per delivery, not bought at sign-up.

The trust score that drives promotion rises with completed deliveries, high ratings, accepted community vouches, and a clean record of no fraud signals (no OTP-skip attempts, no GPS spoofing, no COD shortfalls, no QR mismatches). Negative signals can demote a partner instantly. Money figures are display; the ledger stores paise.

stateDiagram-v2
  [*] --> New
  New --> Bronze: "clean prepaid deliveries + good ratings"
  Bronze --> Silver: "volume + ratings + vouch"
  Silver --> Gold: "sustained record, zero fraud signals"
  Gold --> Platinum: "long clean tenure + surety"
  Platinum --> Gold: "fraud signal / rating drop"
  Gold --> Silver: "complaint / COD shortfall"
  Silver --> Bronze: "demotion on negative signal"
  Bronze --> New: "serious violation"
  New --> Suspended: "fraud detected"
  Suspended --> [*]: "blacklisted (Aadhaar token)"
        

5. Vehicle eligibility & verification

RideChain accepts the full spectrum of rural vehicles. Each type maps to a required document set and a capacity envelope; this mapping is what the matching engine consumes to pick a feasible vehicle for a given parcel size/weight, and what the verification pipeline enforces at onboarding.

6. Booker onboarding — friction-light

A booker is the person sending a parcel, and the design rule is brutal: do not make them do KYC just to book. Friction here directly suppresses the demand the whole network needs. So the booker track is almost nothing — and the rare cases that do need verification are handled with a targeted, minimal KYC-lite step.

1. Phone + OTP + language — the entire mandatory onboarding. Pick a vernacular and you are in.
2. Address book + voice address — save pickup/drop addresses; low-literacy users can add a voice address (spoken landmark + map pin) instead of typing.
3. Book immediately — no KYC required to place a booking. Quote, pay, track — all without an identity check.

7. RideChain Point (PUDO) onboarding

A RideChain Point is a physical handover venue — a kirana, CSC, panchayat office or chai stall — and onboarding one is about verifying a shop, not just a person. The Point becomes a local champion: it stages and collects parcels, confirms handovers, and earns a per-parcel commission.

flowchart TB
  S0["📞 Shop owner: phone + OTP + language"] --> S1["🪪 Shop KYC
owner identity (Easy KYC) + shop details"]
  S1 --> S2["📷 Shop photo + signboard frontage"]
  S2 --> S3["📍 Geo pin (exact PUDO location)"]
  S3 --> S4["🕒 Operating hours"]
  S4 --> S5["📦 Storage capacity
(how many parcels can rest here)"]
  S5 --> S6["📲 Scanner-lite app provisioned"]
  S6 --> S7["🪧 Signboard kit + per-parcel commission"]
  S7 --> S8["✅ Live as a RideChain Point"]
  classDef c fill:#e9f7ef,stroke:#1e8e4e,color:#13602f;
  class S8 c;
        

Once live, the Point gets a scanner-lite app (scan parcel QR, confirm handover OTP, mark stored/collected), a signboard so customers can find it, and a per-parcel commission — consistent with the worked baselines: a drop Point earns ₹6 and a collect Point earns ₹6 on a typical ₹120 single point-to-point booking.

8. Re-verification, suspension & blacklist

Onboarding is not a one-time event — trust decays and documents expire. The platform runs periodic re-KYC and watches document expiry so a partner can never silently age out of compliance.

9. Edge cases & failure modes

Onboarding is designed for the unhappy path — flaky SMS, low literacy, no smartphone, and people actively trying to game the gate. Each risk below has a defined mitigation; the full catalogue lives in the Edge-Case Catalog.