Health savings wallet. Auto-provisioned on first login. Balance, status, and transaction history.
Authentication: All endpoints require Authorization: Bearer <access_token>.Current state: Wallet is a local stub — Transcorp/Juspay integration is in progress. All balance and history data is seeded locally.
The Aarokya health wallet is a ring-fenced digital savings account for healthcare expenses. Unlike a general-purpose prepaid wallet, money loaded into it can only flow toward medical expenses — consultations, pharmacy, insurance premiums, and hospitalisation costs at network hospitals.It is powered by Juspay (payment orchestration) and Transcorp (the RBI-licensed PPI issuer). From a regulatory standpoint, it operates under the RBI’s Prepaid Payment Instrument (PPI) framework.
The wallet is automatically created when the user first logs in — the app never needs to call POST /wallet explicitly (though it is safe to do so idempotently).
Calling Juspay’s API synchronously during login would make login latency dependent on an external service. If Juspay has a 2-second response time, every first login would take 2+ seconds. If Juspay is unavailable, users could not log in at all.Async provisioning:
Makes login fast regardless of external service latency
Isolates authentication availability from payment gateway availability
Allows retry logic without user-facing impact
Wallet creation is async — it never blocks the login response. The app should check wallet status before initiating payments. Status transitions: CREATED → PENDING → IN_PROGRESS → COMPLETED | FAILED | RETRYING
Transcorp is the Prepaid Payment Instrument (PPI) issuer licensed by the Reserve Bank of India. In practical terms, Transcorp is the regulated entity that holds the wallet balance on behalf of each user. Aarokya cannot directly issue a digital wallet — only an RBI-licensed PPI issuer can. Transcorp fills that role.Juspay is the payment orchestration layer that sits between Aarokya’s backend and Transcorp’s core banking system. When Aarokya calls Juspay’s API to register a customer or provision a wallet, Juspay translates those calls into the appropriate operations on Transcorp’s PPI infrastructure.From Aarokya’s perspective:
Aarokya Backend talks to Juspay’s API (REST)
Juspay talks to Transcorp’s PPI system (internal — transparent to Aarokya)
The user’s money is held at Transcorp, not at Juspay and not at Aarokya
Once a wallet is fully provisioned, Juspay returns a transcorp_wallet_id — an identifier that uniquely addresses the user’s wallet account on Transcorp’s system. This identifier looks like wlm_jUT7wpiZAkpFFvaT and is stored in Aarokya’s customer_wallets.transcorp_wallet_id column.Every subsequent balance query, top-up, and transaction history lookup uses this ID to address the correct Transcorp wallet. All path parameters named wallet_id on the wallet endpoints refer to this transcorp_wallet_id.
POST /customers, POST /customers/{ref}/wallets, payment session creation, balance queries
Transcorp
RBI-licensed PPI issuer — holds the actual wallet balance
Via Juspay API (indirect; Aarokya has no direct API calls to Transcorp)
Aarokya’s backend never calls Transcorp directly. All Transcorp operations go through Juspay’s API. The transcorp_wallet_id is a Transcorp-internal identifier surfaced by Juspay and stored by Aarokya for routing subsequent wallet operations.
POST https://sandbox.juspay.in/customers/aarokya_{user_id}/wallets{ "object_reference_id": "wallet_{user_id}", "merchant_id": "cumta"}
The transcorp_wallet_id returned in this call (e.g. wlm_jUT7wpiZAkpFFvaT) is stored in customer_wallets.transcorp_wallet_id and used for all subsequent balance and transaction queries.
Used when the user is paying an insurance premium. The money does NOT go through the health wallet — it goes directly to Narayana Health as a payment.
Juspay session does NOT include payment_rules.load_money
After SUCCESS, POST /insurance/purchase creates the policy record
WALLET_TOPUP
INSURANCE
Juspay session type
Includes payment_rules.load_money
Standard payment session
Money flows to
User’s health wallet
Narayana Health
Status check path
wallet.topup.status
Top-level status
Post-success action
Refresh wallet balance
Call POST /insurance/purchase
When the user pays insurance premium from their wallet balance, use INSURANCE type and set the payment instrument to the wallet (CUMTA_WALLET). This deducts from the wallet balance and pays NH in a single step.
transaction_history is stored as JSONB — a local stub ledger until live Transcorp transaction history is available. Balance is stored in paise (integer) to avoid floating-point rounding errors. Divide by 100 to display in rupees.
