Payments & Integration

1. Overview & principles

The single most important design constraint on RideChain's money stack is regulatory, not technical: the platform holds no money. Funds are never swept into a RideChain bank account that the platform controls. Instead they sit in the payment gateway's escrow / nodal arrangement, and RideChain rides on the gateway's own RBI PA-PG licence. That one decision means RideChain does not need its own RBI nodal account or Payment Aggregator licence — a multi-year, capital-heavy approval we sidestep entirely while remaining compliant.

Five principles govern every line of payment code:

1. Hold no money — escrow lives at the gateway; RideChain only issues instructions.
2. Swappable gateways — a Go interface abstracts Razorpay and Cashfree so routing is a runtime decision, not a deploy.
3. Route by live success rate — pick the rail most likely to succeed for this method/region right now; fail over fast.
4. Webhook is truth — capture, refund and payout state advance only on a signature-verified gateway webhook (with a polling reconciliation safety net), never on a client callback.
5. Append-only ledger — every paise movement is an immutable, double-entry ledger row keyed by idempotency key; balances are derived, never stored as mutable counters.

flowchart LR
  BOOK["📱 Book app / PWA"] --> GO["Go payments module
(abstraction + router)"]
  GO --> ABS["PaymentGateway interface"]
  ABS --> RZP["Razorpay (primary)"]
  ABS --> CF["Cashfree (fallback)"]
  RZP --> ESC["Gateway escrow
(RideChain holds NO money)"]
  CF --> ESC
  ESC -. "release on drop-OTP + POD" .-> PARTNER["Partner / Point payouts"]
  GO --> LEDGER[("Append-only ledger
paise, double-entry")]
  RZP -. "signed webhook (source of truth)" .-> GO
  CF -. "signed webhook (source of truth)" .-> GO
  classDef gw fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  classDef store fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  class RZP,CF gw; class ESC,LEDGER store;
        

2. Payment methods

Rural India is UPI-first and cash-comfortable, so the method mix is built for both. UPI is the primary rail (ubiquitous even in interior markets), the RideChain Wallet smooths repeat use and refunds, COD / cash serves the unbanked and the distrustful, and pay-after-delivery escrow lets a booker authorize now but only be debited when the parcel actually lands.

For pay-on-delivery, three authorization shapes are used depending on the channel and device:

3. The gateway abstraction & success-rate routing

Behind a single Go interface, both gateways look identical to the rest of the backend. The interface exposes the operations RideChain actually needs — create an order, verify a webhook, capture, split, payout, refund — and each vendor has its own adapter. Routing then becomes a pure runtime decision: for this method and region, which rail is succeeding right now?

flowchart TB
  REQ["Payment request
(method, region, amount)"] --> ROUTER{"Router: pick gateway by
rolling success rate
(per method / region)"}
  ROUTER -->|"Razorpay healthy"| RZP["Attempt via Razorpay"]
  ROUTER -->|"breaker OPEN for RZP"| CF1["Attempt via Cashfree"]
  RZP --> OK1{"Success?"}
  OK1 -->|"yes"| REC["Record outcome
(append ledger + metrics)"]
  OK1 -->|"failure / timeout"| RETRY["Retry via Cashfree
(idempotency key preserved)"]
  RETRY --> OK2{"Success?"}
  OK2 -->|"yes"| REC
  OK2 -->|"no"| QUEUE["Queue + notify
(both rails unhealthy)"]
  CF1 --> OK2
  REC --> UPD["Update rolling success-rate
+ circuit-breaker state"]
  UPD --> ROUTER
  classDef gw fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  classDef bad fill:#fdecea,stroke:#c0392b,color:#7b241c;
  class RZP,CF1,RETRY gw; class QUEUE bad;
        

The circuit breaker is the safety valve: each gateway+method has a rolling window of attempts. When the failure rate crosses a threshold the breaker trips OPEN and the router stops sending that combination there (probing with a trickle of HALF_OPEN traffic to detect recovery). This prevents hammering a degraded gateway and keeps the overall success rate high. All retries reuse the same idempotency key so failing over from Razorpay to Cashfree can never double-charge.

4. Escrow & pay-after-delivery lifecycle

Money in a booking is itself a state machine, sitting alongside the booking's own lifecycle (see Booking state machine). The pivot is release: funds leave escrow toward a partner or Point only after that leg's drop-OTP + POD are verified. For a relay booking, release is per leg — leg 1's partner is paid on leg 1's handover even before leg 2 completes.

stateDiagram-v2
  [*] --> ORDER_CREATED
  ORDER_CREATED --> AUTHORIZED: "booker pays / authorizes (UPI)"
  ORDER_CREATED --> FAILED: "pay-in fails / timeout"
  AUTHORIZED --> CAPTURED: "webhook captured (signature-verified)"
  CAPTURED --> ESCROW_HELD: "funds held at gateway"
  ESCROW_HELD --> SPLIT_RELEASED: "drop-OTP + POD per leg"
  SPLIT_RELEASED --> SETTLED: "payouts confirmed (Route / Easy Split)"
  ESCROW_HELD --> REFUND_INITIATED: "no partner / cancel / fail"
  SPLIT_RELEASED --> REFUND_INITIATED: "partial relay failure"
  REFUND_INITIATED --> REFUNDED: "gateway refund webhook"
  SETTLED --> CHARGEBACK: "bank dispute raised"
  CHARGEBACK --> SETTLED: "resolved with POD + OTP evidence"
  CHARGEBACK --> REFUNDED: "resolved for booker"
  FAILED --> [*]
  REFUNDED --> [*]
  SETTLED --> [*]
        

Pay-after-delivery threads the same machine but defers capture: the booker reaches AUTHORIZED at booking (a mandate/auth hold), and CAPTURED is delayed until the drop-OTP fires. If delivery fails, the auth is simply voided — the booker is never debited for a parcel that did not arrive.

5. Integration sequence

End to end, a pay-in is three idempotent legs: create an order, let the booker pay, and advance state only on the signature-verified webhook. A background reconciliation job covers any webhook that is lost or delayed.

sequenceDiagram
  autonumber
  participant APP as "Book app / PWA"
  participant GO as "Go payments module"
  participant GW as "Gateway (RZP → CF)"
  participant LED as "Append-only ledger"
  participant MA as Matching
  APP->>GO: "Place booking (idempotency-key)"
  GO->>GW: "Create order (amount in paise)"
  GW-->>GO: "order_id"
  GO-->>APP: "order_id + pay intent (UPI)"
  APP->>GW: "Pay (UPI collect / QR)"
  Note over APP,GW: "Client may show 'paid' optimistically — not trusted"
  GW-->>GO: "WEBHOOK: payment.captured (signed)"
  GO->>GO: "Verify HMAC signature + dedupe by event-id"
  GO->>LED: "Append CAPTURED → ESCROW_HELD (idempotent)"
  GO-->>GW: "200 OK (ack webhook)"
  GO->>MA: "Dispatch matching"
  Note over GO,GW: "Reconciliation job polls gateway for any missed webhook"
        

Three integration guarantees make this robust:

1. Webhook signature verification — every inbound webhook's HMAC is verified against the raw request body using the gateway secret. An unverified or tampered webhook is rejected and logged; it never advances state.
2. Idempotency keys — the client's booking idempotency-key flows into order creation, and the gateway's event-id dedupes webhooks. A replayed or duplicate event maps to the same ledger entry and changes nothing twice.
3. Reconciliation job — a periodic job fetches gateway settlement/payment status for any order stuck in AUTHORIZED or missing its webhook, and applies the same idempotent transition the webhook would have. This is the lost-webhook safety net (see §8).

6. The OTPs in payment

RideChain uses four OTPs across a journey (booking, pickup, drop, payment — see Booking & Delivery Flow §5). Three of them touch money directly: the booking OTP confirms intent, the payment OTP authorizes a pay-after-delivery debit, and the drop-OTP is what releases escrow.

flowchart LR
  PO["Payment OTP
(authorize debit)"] --> AUTH["Order AUTHORIZED
(no capture yet)"]
  AUTH --> WAIT["Parcel in transit
(escrow / auth held)"]
  WAIT --> DO{"Drop-OTP + POD
verified?"}
  DO -->|"yes"| CAP["Capture + SPLIT_RELEASED
(per leg)"]
  DO -->|"no / fail"| VOID["Void auth → no debit"]
  classDef good fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
  classDef bad fill:#fdecea,stroke:#c0392b,color:#7b241c;
  class CAP good; class VOID bad;
        

7. COD & cash reconciliation

Cash never disappears into a black box. When a partner collects cash (COD), every rupee is logged as a digital ledger event the moment it changes hands, then reconciled at the Block Hub or against the partner's wallet, and finally settled to the platform's split structure. The partner is effectively holding the platform's money in physical form, so trust limits and a tight digital trail are essential.

flowchart TB
  COL["Partner collects cash
(COD on delivery)"] --> EV["Log digital ledger event
(amount in paise, parcel-id, geo, time)"]
  EV --> REC{"Reconcile at hub / wallet"}
  REC -->|"deposit at hub or top-up wallet"| OK["Cash matched to ledger"]
  REC -->|"shortfall"| SHORT["Debit partner wallet
+ trust-tier hit"]
  OK --> SET["Settle splits
(partner / Point / platform)"]
  classDef bad fill:#fdecea,stroke:#c0392b,color:#7b241c;
  class SHORT bad;
        

COD limits are tiered by trust. A brand-new partner can carry only small COD totals before a mandatory hub deposit; as their verified history and successful reconciliations grow, the ceiling rises. The same applies to bookers/receivers paying COD on high-value parcels. Trust tiers are defined in Onboarding & KYC.

8. Refunds, chargebacks, failures & reconciliation

Because money is captured into escrow up front, RideChain must be excellent at giving it back cleanly. Refund triggers, partial refunds for partial relays, chargeback defence, and a daily reconciliation job together keep the ledger and the gateway perfectly in agreement.

flowchart TB
  CRON["Daily reconciliation job"] --> PULL["Pull gateway settlement report
(Razorpay + Cashfree)"]
  PULL --> DIFF{"Diff vs internal
append-only ledger"}
  DIFF -->|"match"| CLEAN["Mark reconciled"]
  DIFF -->|"missing webhook"| APPLY["Apply idempotent transition
(replay-safe)"]
  DIFF -->|"unexplained mismatch"| FLAG["Flag to ops queue
(manual review)"]
  subgraph Recovery["Lost-webhook recovery"]
    POLL["Poller checks orders stuck
in AUTHORIZED"] --> APPLY
  end
  APPLY --> CLEAN
  classDef bad fill:#fdecea,stroke:#c0392b,color:#7b241c;
  class FLAG bad;
        

9. Compliance

Holding no money keeps RideChain on the right side of the heaviest regulation, but several obligations still apply. They are handled by riding on the gateways' licences and by never storing what we are not allowed to.

10. Edge cases & failure modes

The payment stack assumes gateways flake, networks drop, and webhooks vanish. Every money-touching failure has a defined, idempotent mitigation; the full catalogue lives in the Edge-Case Catalog.