Skip to main content

Onboarding

Validate participant update

Confirms a participant update by presenting the SMS passcode and the transactionId returned by /v2/participant/update.

GET/update/validate

### Business purpose

Changing a participant's encryption certificate or callback endpoint changes where encrypted claims data is delivered and who can decrypt it, so the registry does not apply such updates on an API call alone. /v2/participant/update stages the change and sends a passcode to the registered mobile number; this call confirms it. It is step 4 of the production onboarding sequence and the same approval mechanism protects every later certificate or bridge rotation done through the v2 update.

### When to use

Call it after /v2/participant/update returns a transactionid and the passcode arrives by SMS, within the 24-hour validity window. The production URL is https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/update/validate?transactionId=""&passcode="". It is also the closing step of the annual key-rotation checklist when rotation is done via /v2/participant/update. The passcode-free alternative for certificate-only changes is /v2/update/cert. No workflow or x-hcx-status codes apply.

### Preconditions

- The participant is already registered and its creation was confirmed via /validate. - A completed /v2/participant/update that returned a transactionid, with the matching passcode received on the registered mobile number. - The call is made within 24 hours; each new update trigger generates a new transaction id and passcode. - Bearer token with the Bearer prefix in bearer_auth and Accept: application/json; parameters go in the query string.

### Postconditions

HTTP 200 with a bare string body (operation particiapntUpdateValidate, response type string). The staged certificate and endpoint URL become the participant's live registry values, which is what counterparties will receive from /fetch/certs and what the gateway will use for callback delivery. There is no asynchronous callback. Errors return the registry ErrorResponse envelope with 400, 404 or 500.

### Common mistakes

- Assuming the update is live as soon as /v2/participant/update returns; until this call succeeds counterparties may still fetch the old certificate. - Presenting a passcode from a previous update attempt after a new one was triggered. - Letting the 24-hour window lapse and then retrying validation instead of re-issuing the update. - Calling /validate (creation) instead of /update/validate. - Losing the transaction id, which requires repeating the update request.

### Best practices

- Rotate keys in two phases: keep the old private key available for decrypting inbound callbacks until the update is validated and cached certificates (24-hour TTL on the payer side) have refreshed. - Persist transactionid with its 24-hour expiry and record who completed validation, for audit. - Never log the passcode; treat it as a one-time credential. - After success, call /participant/search on your own code to confirm encryption_cert and endpoint_url reflect the change.

### Related scenario

A year after go-live a payer's security team rotates the encryption key pair. The integrator generates a new self-signed X.509 certificate, Base64-encodes it and calls /v2/participant/update with participantcode and encryptioncert. The registry returns status and a new transactionid and sends a passcode to the registered mobile. Within the hour the team calls GET /update/validate with both values; on 200 the new certificate is live. Providers that cached the old certificate pick up the new one at their next 24-hour refresh, and the payer keeps the old private key for one more day to decrypt in-flight callbacks.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Query parameters

transactionIdstringRequired
passcodestringRequired

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

Responses

200

HTTP 200 with a bare string body (operation particiapntUpdateValidate, response type string).