Skip to main content

Payer: send the task outcome

Payer returns a Task bundle with Task.status completed whose Task.output references a ClaimResponse carrying the reprocess or cancellation outcome.

POST/v1/task/on_submit

Business purpose

This callback closes the appeal or cancellation the provider opened on /v1/task/submit. It carries the payer's final decision on a reprocess (approved, partially approved, queried or rejected) or confirms a pre-authorisation cancellation, in the same ClaimResponse shape used for ordinary adjudication so hospitals can reuse their parsers. Because the reprocess response is final within the workflow, it delivers closure, a clean audit trail and reduced ambiguity for both sides, which is the point of moving disputes inside NHCX.

When to use

The payer calls it to answer a reprocess or cancellation Task. The answer is a completed Task that points at a ClaimResponse with the new decision. A cancellation is confirmed on workflow PC02.

Preconditions

  • The payer answered the incoming Task with 202 within 30 seconds.
  • A valid access token and the provider's certificate.
  • The header reuses the Task's x-hcx-correlation_ID.
  • The ClaimResponse inside is built like any other decision.

Postconditions

  • NHCX answers 202 and forwards the answer to the provider.
  • The provider reads the ClaimResponse the Task points at, like any other decision.
  • The reprocess decision is final. A cancelled pre-authorisation needs a new one if treatment resumes.

Common mistakes

  • Looking for the ClaimResponse directly in the bundle instead of following the Task's output.
  • Reading outcome complete as approval. A rejection is also complete.
  • Sending a new correlation ID on the answer.
  • Sending a bare ClaimResponse without the Task around it.

Best practices

  • Payer: acknowledge first, re-adjudicate asynchronously, then post the Task bundle with the outcome workflow ID and ClaimResponse nested in Task.output.
  • Provider: share the ClaimResponse parser between /v1/claim/on_submit and this callback; only the extraction path differs.
  • Branch on adjudication reason as well as outcome; check processNote for reductions or query text.
  • "Terminate the appeal branch of the case state machine on 252 or 253. On 254, note that NHCX publishes no workflow code for the answer: the handbook's 19 is the preauthorisation query response code, so confirm with the payer how it wants the answer sent."
  • Be idempotent on correlation ID; expect redeliveries.
  • Fresh API_call_ID, IST timestamp, responder status on the callback header.

Related scenario

A scheme payer's TPA receives a reprocess Task on a rejected claim with the missing implant invoice attached. Its endpoint returns 202 and the case reopens for re-adjudication with the original claim, the new document and the justification. The reviewer approves at the package rate, and the TPA posts /v1/task/on_submit: a Task bundle, status completed, Task.output referencing a ClaimResponse with outcome complete, workflow 252, under the claim's correlation ID. The hospital acknowledges within 30 seconds, extracts the ClaimResponse from Task.output, marks the appeal closed and awaits the payment notice on /v1/paymentnotice/request.

Specification

Chapter Cancel, reprocess and shortfall of the NHCX integration specification.

Authorizations

bearer_authapiKeyRequired

Every NHCX call carries the access token from the session call in a header named bearer_auth, as the word Bearer, a space and the token. NHCX reads bearer_auth, not Authorization.

Example Bearer <access token>

Protected header

These fields go in the JWE protected header of payload, not as HTTP headers. Building and sending a JWE shows how to prepare and encrypt the payload, and Receiving a callback how to decrypt one.

algstringRequired

Key management algorithm. Always RSA-OAEP-256: the content key is wrapped with the recipient's RSA public key.

Example RSA-OAEP-256

encstringRequired

Content encryption algorithm. Always A256GCM.

Example A256GCM

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

Example <payer participant code>

x-hcx-recipient_codestringRequired

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

Example <provider participant code>

x-hcx-api_call_idstringRequired

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

Example <uuid>

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. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.

Example <uuid>

x-hcx-correlation_idstringRequired

The thread that ties a request to its answers. The correlation ID rule says when to reuse it. Mandatory on the envelope.

Example <uuid>

x-hcx-workflow_idstring

Which step, or which case. The workflow code explains both readings. Optional on the envelope.

Example 252

x-hcx-timestampstringRequired

The time the message was made. Timestamp gives the format. Mandatory on the envelope.

Example <iso timestamp>

x-hcx-statusstringRequired

Where this message stands. Status words lists the values. Mandatory on the envelope.

Example response.complete

x-hcx-ben-abha-idstring

The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

Example <14-digit ABHA number>

Body

typestringRequired

Always JWEPayload. Every response (on_) call sends it beside payload.

One of JWEPayload

payloadstringRequired

Responses

202

The gateway returns HTTP 202 with the StatusSuccessResponse envelope (400, 404, 500 in the same shape) and forwards the bundle to the provider, which must acknowledge within 30 seconds.

timestampstring
api_call_idstring
correlation_idstring
resultobject
result.sender_codestring
result.recipient_codestring
result.entity_typestring
result.protocol_statusstring
errorobject
error.codestring
error.messagestring

Callbacks​