Skip to main content

Recipient: answer a status check

The answer to a status request, delivered to the sender that asked. The x-hcx-status in the protected header says where the message you asked about got to.

POST/v1/on_status

The payload is an empty string.

Business purpose

It separates "did my message arrive" from "what did the payer decide". A sender learns whether a quiet case is still held by the exchange, has reached the recipient, or is dead, without resubmitting it and creating a duplicate.

When to use

Every participant that sends /v1/status hosts this path. It carries the answer to your status request.

Preconditions

  • You sent /v1/status and kept track of which request it asked about.
  • Your callback URL is registered and answers 202 within 30 seconds.

Postconditions

Read x-hcx-status in the header. request.dispatched means the message reached the recipient, and request.queued means NHCX still holds it. request.stopped means the request is dead, so a retry needs a new correlation ID. Answer 202.

Common mistakes

  • Expecting a bundle. The payload is an empty string.
  • Matching on the original request's correlation ID instead of your status request's.
  • Retrying a stopped request on its old correlation ID.

Best practices

  • Keep every API_call_ID you send. Without it you cannot ask the question at all.
  • Act on request.stopped at once, and treat request.dispatched as a reason to wait for the payer.
  • Ask from a support screen when a case has gone quiet for longer than the payer's expected turnaround, not on a timer.

Related scenario

A pre-authorisation has had no answer for longer than the payer's usual turnaround. The support screen sends /v1/status with that request's API_call_ID as the correlation ID. The answer arrives here with an empty payload and x-hcx-status request.stopped, so the desk knows the request is dead rather than slow, and resubmits it with a fresh correlation ID.

Specification

Chapter NHCX adapter (Optional) 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 <participant code>

x-hcx-recipient_codestringRequired

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

Example <recipient code>

x-hcx-api_call_idstringRequired

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

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 <correlation id>

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

Body

typestringRequired

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

One of JWEPayload

payloadstringRequired

Responses

200

Read x-hcx-status from the protected header.

timestampstring
api_call_idstring
correlation_idstring
errorobject
error.codestring
error.messagestring

Callbacks​