NPS Swasthya – HBA API Contract

This document is a provider specification: NPS Central hosts every API in it and the HBA calls them. The paths, request and response bodies, status values and error codes are the same whichever CRA holds the PRAN. Differences between the CRAs (transport, encryption, response codes and wording) are absorbed by NPS Central. CRA names and CRA-native error codes never appear in a response; where a CRA's own sentence is passed through, its name is replaced with "the recordkeeper".

Field names are the CRAs' own. CAMS and KFintech use the same snake_case field names and values (for example eligibility: "Y", net_eligible_balance, category: "WDL_AUTH_PARTIAL", wdl_ack_id), and this contract uses them unchanged. The values are common to every CRA: a flag is always Y or N, an amount is always a JSON number, req_id is always a string and withdrawal_type is always WDL_AUTH_PARTIAL or WDL_AUTH_FULL, whichever CRA answered. Every value the HBA sends (category, patient_type) is likewise one set, translated by NPS Central for each CRA. The few fields NPS Central adds (id, status, checked_at, as_of, otp_expires_at, consent_expires_at, failure_reason) follow the same case. The CRA's OTP token and its raw access_key are never returned.

Recordkeepers served in this version: CAMS and KFintech. A PRAN held by Protean is answered with 501 SWASTHYA_WITHDRAWAL_UNSUPPORTED. Eligibility (Part I) and Withdrawal (Part III) for Protean will be served through the same APIs once NPS Central enables them, with no HBA change. Protean offers no balance confirmation (it has no AUTH OTP), so Balance (Part II) will go on answering 501 for a Protean PRAN.

The CRAs authorise each kind of call differently, and this contract follows them exactly. Every OTP in this document is the CRA's own. It is sent by the CRA to the mobile number registered against the PRAN, and checked by the CRA. NPS Central sends no OTP of its own, and the HBA does not need to log the subscriber in first.

The HBA authenticates with the OAuth 2.0 client credentials grant (RFC 6749 §4.4). Its client credential goes only to the token endpoint. Every API call carries the short-lived access token the endpoint returns.

The HBA receives its clientId, its client secret, and its encryption key if encryption is used.

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 900,
  "scope": "swasthya:eligibility swasthya:balance swasthya:withdraw" }

TLS protects every call. On top of it, the HBA's registration sets a message encryption policy. No request header changes it.

Encryption uses the NPSC envelope: a JSON envelope sealed with AES-256-GCM under the encryption key issued to the HBA, sent with Content-Type: application/vnd.npsc.envelope+json. No JOSE library is needed. A request with a body is answered in the envelope when it was sent in one. A request with no body (Withdrawal – Status) is answered in the envelope when its Accept header is application/vnd.npsc.envelope+json; under the required policy, send this header on that call. Not encrypted: the token endpoint (plain OAuth) and the X-Request-Id response header.

{
  "version": "NPSC1",
  "keyId": "jwe_3f9c…",
  "randomNo": "00112233445566778899aabbccddeeff",
  "timestamp": 1760261400,
  "encData": "oKGio6SlpqeoqaqrW6Zcn0RWG8Li…"
}

Sealing a request:

Opening a response is the same with RES in place of REQ, the response's own randomNo, timestamp and keyId, and the request's method and path. Because the key is bound to the access token and the AAD to the method and path, a body sealed for one call cannot be replayed to another route or under another token. Refusals: a bad shape, a stale timestamp, a reused randomNo, a keyId that is not live, or a body that does not open are all 400 ENVELOPE_INVALID. A test vector and Node and Java reference code are in Annexure C. Check the implementation against the test vector before the first UAT call.

No Idempotency-Key header is needed on these APIs. Duplicate protection is built into the withdrawal flow (3.7).

Absent and empty are different: an optional response field with no value is omitted, never sent as an empty string. Send only the request fields defined for each API; a field not defined may be refused with 400 REQUEST_INVALID.

Ownership. Everything an HBA creates belongs to its clientId. Another HBA presenting the id receives the same 404 as for an id that does not exist.

A successful response body carries the API-specific fields described in each Part. Every error response (except the token endpoint's, 3.2.4) is a problem document with Content-Type: application/problem+json (encrypted under the required policy). HBAs branch on category and code, never on detail text.

HTTP status codes: 200/201/202 for a processed call; 400 for a body that could not be read or failed field validation; 401 for authentication (including a route outside the token's scopes, and an invalid or expired access_key); 404 for an id that does not exist or is not the HBA's (deliberately one answer); 409 for a state conflict; 422 for a request that was read and refused, including CRA refusals; 429 for rate limiting; 501 for an unsupported recordkeeper; 503 when the CRA could not be reached. A withdrawal the CRA refuses after submission is not an HTTP error: Withdrawal – Status answers 200 with status: FAILED and a failure_reason (Part III).

Planned maintenance on either side requires 48 hours' notice. Incidents are reported per the escalation matrix exchanged at onboarding.

NPS Central finds the CRA holding the PRAN (the CRA where the account is active), runs the CRA's enrolment check, and asks the CRA to send its AUTH OTP to the mobile registered against the PRAN.

NPS Central validates the OTP at the CRA, receives the CRA's access_key, reads the first balance with it, and returns the access_key sealed.

A wrong OTP is 422 SWASTHYA_OTP_INVALID; the subscriber may retype it within the window. A spent or expired CRA token is 409 SWASTHYA_OTP_EXPIRED, and a request whose 15 minutes have passed is 404 SWASTHYA_CONSENT_NOT_FOUND. Either way, start again with a new Consent Request.

NPS Central opens the access_key, checks that it was issued to this HBA for this PRAN, and reads the balance from the CRA with the credential inside. Each call is a live read; nothing is cached.

What NPS Central does: finds the CRA holding the PRAN; runs the enrolment check (refuses unless the PRAN exists, holds an NPS Swasthya scheme, has a balance and is not an NPS Vatsalya PRAN); runs the eligibility check for the amount (refuses only when the CRA says eligibility: N; if the check cannot be made, continues, since the CRA checks again); asks the CRA to send the withdrawal OTP for the category and amount the HBA sent. NPS Central does not derive or change the category; the CRA decides whether it allows it. The amount is fixed at this step.

Submits the subscriber's withdrawal OTP with the patient type, as the CRA's withdrawal request takes them. The CRA can take 20–40 seconds, so NPS Central answers at once with 202 SUBMITTING and calls the CRA in the background. The OTP is single use: the first submission claims the withdrawal (3.7).

Response: HTTP 202 with the withdrawal object (6.6.b), status: SUBMITTING.

Poll every 3–5 seconds after submission until the status is terminal. Readable for 60 minutes after initiation. The request takes only withdrawalId (path), prefix wdl_.