Skip to main content

Payment notice

Payment notice request

Payer pushes a Task bundle with PaymentNotice and PaymentReconciliation (amount, TDS, UTR) to the provider via NHCX after approving a claim.

POST/v1/paymentnotice/request

### Business purpose

Every other flow exchanges decisions; the payment notice is the only one that tells the hospital whether the money actually moved. It formally notifies the provider that a payment has been initiated, processed or settled against an approved claim, carrying the net amount, TDS deduction, payment date and the UTR. Hospitals need it to reconcile bank receipts to claims and close the episode; payers need it as the structured, auditable record of settlement.

### When to use

Payer-initiated, after the final claim is approved (workflow 26). The same bundle shape is sent up to three times as the money progresses: 30 PAYMENT_INITIATED, 31 PAYMENT_PROCESSED and 33 PAYMENT_SETTLED, when the UTR becomes available in PaymentReconciliation.paymentIdentifier.value. The NHA status sheet frames these as x-hcx-status request.initiated because the payer is authoring a new request to the provider; the workbook sample shows x-hcx-workflow_id 11 as a placeholder. The bundle is a Task with code deliver and status requested, plus PaymentNotice (paymentStatus paid), PaymentReconciliation and both Organisations.

### Preconditions

- The claim has received a response.complete approval and a payment has been initiated in the payer's banking system. - The payer holds a valid Bearer token and has fetched the provider's certificate; the bundle is JWE-encrypted for the provider. - Protected header carries request.initiated, a fresh correlation UUID for this notice cycle (the workbook says same as the API caller ID), the payer as sender and the provider as recipient, and an IST timestamp. - PaymentNotice.amount and PaymentReconciliation.paymentAmount carry the net amount; detail lines itemise TDS and Payment; the claim number is carried as identifier type CLN. - Valid provider bank details exist on the payer side (PAYR-1020 otherwise).

### Postconditions

NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type payment) and forwards the bundle asynchronously to the provider's registered callback endpoint, which must acknowledge with 202 within 30 seconds. The provider then sends its own acknowledgement Task (status completed, output paymentack, workflow 17) on /v1/paymentnotice/on_request; only after that acknowledgement is the payment lifecycle considered closed. Protocol failures at the provider come back as a ProtocolResponse with x-hcx-error_details. Statuses 400, 404 and 500 carry the same schema.

### Common mistakes

- Provider side: expecting a Claim or ClaimResponse; the payment notice is a Task bundle and the money fields live in PaymentReconciliation. - Provider side: reading the UTR before workflow 33, or parsing the scroll-style UTR (for example UTR000000000001) as a bank RRN. - Provider side: relying on Task.description text for logic; the published sample contains a typo (Recived the payment). - Provider side: returning 200 or a malformed body on receipt, which triggers five retries and deletion. - Payer side: sending the notice before the claim is closed by response.complete, or without valid provider bank details (PAYR-1020). - Both sides: the FAQ's sandbox base URL for payment notice is printed without a slash between host and path; cross-check against the endpoint index.

### Best practices

- Payer: send 30, 31 and 33 as the transfer progresses and populate paymentIdentifier with the UTR at 33; keep TDS and Payment detail lines consistent with the gross claim amount. - Provider: persist the UTR, TDS and net amount against the claim for audit and dispute resolution, and mark the claim SETTLED only on 33. - Provider: acknowledge with 202 within 30 seconds, be idempotent on correlation ID, then send the paymentack Task. - Both: note the source conflict on whether the acknowledgement goes to /v1/paymentnotice/on_request or /v1/task/submit; the API contract supports on_request, so confirm with the counterparty during onboarding. - Both: use IST timestamps and echo the correlation ID through the acknowledgement.

### Related scenario

Three days after approving claim CL0000000001 for 2430 INR, the state health agency initiates a bank transfer of 2187 INR after 243 INR TDS. Its bridge builds a Task bundle with code deliver, a PaymentNotice with amount 2187 and status paid, and a PaymentReconciliation with the TDS and Payment detail lines, and posts it to /v1/paymentnotice/request under workflow 30. NHCX returns 202 and delivers it to the hospital, which acknowledges within 30 seconds. When the transfer settles the payer sends a second notice under 33 carrying the UTR; the hospital persists it and responds on /v1/paymentnotice/on_request with a paymentack Task.

### Specification

Chapter [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement) 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.

Headers

bearer_authstringRequired

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

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

x-hcx-recipient_codestringRequired

The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.

x-hcx-api_call_idstringRequired

Fresh on every message, including responses. Mandatory on the envelope.

x-hcx-request_idstring

One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope.

x-hcx-correlation_idstringRequired

The thread. See the rule below. Mandatory on the envelope.

x-hcx-workflow_idstring

Which step, or which case. See the two readings below. Optional on the envelope.

x-hcx-timestampstringRequired

See the format note below. Mandatory on the envelope.

x-hcx-statusstringRequired

Where this message stands. Values below. Mandatory on the envelope.

x-hcx-ben-abha-idstringRequired

The beneficiary's ABHA number. Mandatory on every exchange, including those with no beneficiary in the payload. Mandatory on the envelope.

Body

payloadstring

Responses

202

NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type payment) and forwards the bundle asynchronously to the provider's registered callback endpoint, which must acknowledge with 202 within 30 seconds.

Callbacks​

  • After this call, ABDM posts Receive payment notice request to v1_paymentnotice_request. Open the callback.