Wallet & Payments

Phase 2 — rider wallet, top-ups, promo codes, payments.

Your wallet

GET  /api/wallet              → your balance (minor units)
POST /api/wallet/topup        → { amountMinor, idempotencyKey }   (test/dev)

Balances are held in an immutable ledger; every change is a recorded transaction you can never lose track of.

Topping up via a payment gateway

GET  /api/payments/providers  → available gateways (e.g. manual, stripe)
POST /api/payments/topup
{ "amountMinor": "50000", "idempotencyKey": "…", "provider": "stripe" }

• Cash / manual: captured immediately, wallet credited at once.
• Card (Stripe): a charge is created. In markets that require card authentication (e.g. India's 3-D Secure), you complete the authentication, and the wallet is credited when the gateway confirms the payment (via webhook) — exactly like other apps that send you an OTP.

The same idempotency key never charges or credits twice.

Promo codes

POST /api/promo/validate
{ "code": "WELCOME20", "fareMinor": "13173" }
→ { discountMinor, netFareMinor }

Validates the code for you and the fare (limits, validity, minimum fare) and shows the discount before you book.

Referrals

When you refer a friend (rider or driver), both of you receive a wallet credit once the referral's reward conditions are met.

Cancellations

Cancelling before a driver accepts, or within the free window after acceptance, is free. After that a small fee may apply (shown before you confirm). A no-show fee applies if the driver arrives and you're not there.