HDFC Bank SmartWealth — API integration & OpenFinance services

Deliverables checklist

• OpenAPI 3.1 specification for every endpoint we ship
• Protocol and auth flow report (OAuth, token refresh, MPIN binding, AA consent IDs)
• Runnable source for login, holdings, SIP and capital gains APIs (Python + Node.js)
• Integration test suite plus synthetic data fixtures for CI
• Compliance pack: KYC/PAN handling, AA consent template, retention policy
• Operational runbook: rate limits, retry/backoff, error taxonomy

Technical implementation

Three representative snippets — a session login, a holdings query, and a capital gains export webhook. Real shipped code includes pagination, retries, AA consent piggybacking, and idempotency keys.

// 1) Session login (pseudocode)
POST /api/v1/smartwealth/auth/login
Content-Type: application/json

{
  "username": "PAN_OR_CIF",
  "mpin": "<encrypted>",
  "device_fingerprint": "<hash>"
}

200 OK
{ "access_token": "eyJ...", "refresh_token": "...",
  "expires_in": 900, "consent_id": "AA-CONSENT-..." }

// 2) Mutual fund holdings query
GET /api/v1/smartwealth/portfolio/holdings?pan=ABCDE1234F
Authorization: Bearer <ACCESS_TOKEN>
X-Consent-Id: AA-CONSENT-...

200 OK
{
  "as_of": "2026-05-03",
  "holdings": [
    {"isin":"INF179KC1Z25","amc":"HDFC AMC",
     "scheme":"HDFC Flexi Cap Fund - Direct - Growth",
     "units":1023.456,"nav":1872.55,"invested":1500000,
     "current_value":1916083.51,"xirr":0.143}
  ]
}

// 3) Capital gains webhook delivery
POST https://your-app.example.com/webhooks/sw-capgains
X-OFL-Signature: t=1746240000,v1=...

{
  "event":"capgains.report.ready",
  "ay":"2025-26",
  "stcg_total":48230.12,
  "ltcg_total":126985.07,
  "report_url":"https://api.openfinance-lab.com/files/cg/abc.json",
  "expires_at":"2026-05-04T12:00:00Z"
}

Compliance & privacy

SmartWealth integrations sit at the intersection of two Indian regulators: the Reserve Bank of India for the underlying bank rails and FD products, and the Securities and Exchange Board of India for the mutual fund and advisory layer. We work under explicit user authorization or licensed NBFC-AA pathways under the India Account Aggregator framework, which the RBI, SEBI, IRDAI and PFRDA jointly designed for consent-based financial data sharing.

By 2025 the AA ecosystem had crossed 240 million consent requests and 180 million linked accounts, and SEBI specifically lists mutual fund units among the financial information types that can flow through AA. That means SmartWealth holdings can be retrieved either through user-authorized session APIs or through a consent ID issued by an AA — we support both and recommend AA wherever the client is an FIU.

Beyond AA, our default delivery includes data minimization (we only request the fields the use case needs), encryption at rest and in transit, redaction of free-text fields containing personal data, and a retention policy aligned with the RBI 10-year audit window.

Data flow / architecture

A typical SmartWealth integration is a four-node pipeline:

1. Edge / consent layer — captures user OAuth or AA consent and holds short-lived tokens.
2. Ingestion service — calls SmartWealth endpoints (holdings, SIP, FD, capital gains) with retry, backoff, and idempotency.
3. Storage — Postgres for relational portfolio rows, S3/WORM for raw responses and audit logs.
4. Consumer API — clean REST/GraphQL for the customer's app, plus webhooks for SIP execution and capital gains report readiness.

The same shape scales from a single advisor with a few hundred PANs to a family-office stack with millions of daily NAV updates.

About us

OpenFinance Lab is an independent technical studio focused on mobile app interface integration, authorized API delivery, and OpenData/OpenFinance pipelines. Our team has shipped integrations across Indian banks, brokers, AMCs, payment networks, and overseas neobanks, and we actively track NPCI, RBI, and SEBI guidance so deliveries do not age out within a quarter.

• Wealth, payments, lending, insurtech and cross-border clearing
• Enterprise API gateways, security reviews, and AA consent design
• Custom Python, Node.js and Go SDKs with test harnesses
• End-to-end pipeline: protocol analysis → build → validation → compliance pack
• Source code delivery from $300 — runnable API source plus full docs; pay after satisfactory delivery
• Pay-per-call hosted API — no upfront cost, billed per call, ideal for usage-based teams

Contact

For a SmartWealth scope quote, an Account Aggregator consultation, or a multi-app wealth feed, open our contact page:

Contact page

Engagement workflow

1. Scope confirmation: which SmartWealth surfaces (holdings, SIP, capital gains, FD) and which consent model.
2. Protocol analysis and API design (2–5 business days, complexity-dependent).
3. Build, internal validation, and AA sandbox dry-run (3–8 business days).
4. Documentation, test cases, and compliance pack (1–2 business days).
5. Typical first delivery: 5–15 business days. Third-party AA or AMC approvals may extend timelines.

FAQ

What do you need from me to start a SmartWealth integration?

How long does a first delivery take?

How is regulatory compliance handled for an Indian wealth app?

Can you also pull external mutual fund holdings, not only HDFC ones?