Payer Use Cases
Cover the NHCX sandbox exit flows that a payer system must support.
A payer system must cover the flows in this page for NHCX sandbox exit. Use Requests and Responses for bundle and field rules. Use Provider Use Cases to compare the counterparty flows.
Response rule
A payer must validate each inbound bundle before it sends a callback.
Encrypt a success payload with the recipient public key.
Send ProtocolResponse for protocol, validation, or decryption errors.
Common validation rules
| Rule | Payer action |
|---|---|
| FHIR profile | Validate each payload against the NRCES profile. |
| API call ID | Create a new ID for each callback call. |
| Correlation ID | Use the request API call ID as the callback correlation ID. |
| Receiver code | Match the callback receiver code to the request sender code. |
Use cases
1. Link ABHA with Policy
| Item | Requirement |
|---|---|
| API to call | POST /participant/link/abha/policy |
| API to implement | None |
| API owner | NHCX |
| Bundle | None |
| Status | None |
| Callback logic | None |
2. Get Policy
| Item | Requirement |
|---|---|
| API to call | POST /participant/get/policies |
| API to implement | None |
| API owner | NHCX |
| Bundle | None |
| Status | None |
| Callback logic | None |
3. De-Link ABHA from Policy
| Item | Requirement |
|---|---|
| API to call | POST /participant/delink/abha/policy |
| API to implement | None |
| API owner | NHCX |
| Bundle | None |
| Status | None |
| Callback logic | None |
4. Get Participant List
| Item | Requirement |
|---|---|
| API to call | POST /fetch/participants/list |
| API to implement | None |
| API owner | NHCX |
| Bundle | None |
| Status | None |
| Callback logic | None |
5. Get Public Key
| Item | Requirement |
|---|---|
| API to call | POST /fetch/certs |
| API to implement | None |
| API owner | NHCX |
| Bundle | None |
| Status | None |
| Callback logic | None |
6. Get Auth Token
| Item | Requirement |
|---|---|
| API to call | POST /get/session |
| API to implement | None |
| API owner | NHCX |
| Bundle | None |
| Status | None |
| Callback logic | None |
7. Respond to Coverage Eligibility
| Item | Requirement |
|---|---|
| API to receive | POST /v1/coverageeligibility/check |
| Callback API to call | POST /v1/coverageeligibility/on_check |
| Callback API owner | Provider |
| Success bundle | CoverageEligibilityResponseBundle |
| Success status | response.completed |
| Callback logic | Send a JWE success payload or send ProtocolResponse. |
8. Respond to Insurance Plan Request
| Item | Requirement |
|---|---|
| API to receive | POST /v1/insuranceplan/request |
| Callback API to call | POST /v1/insuranceplan/on_request |
| Callback API owner | Provider |
| Success bundle | TaskBundle with InsurancePlanBundle output |
| Success status | response.complete |
| Callback logic | Send insurance plan details through NHCX. |
9. Respond to Preauthorization
| Item | Requirement |
|---|---|
| API to receive | POST /v1/preauth/submit |
| Callback API to call | POST /v1/preauth/on_submit |
| Callback API owner | Provider |
| Success bundle | ClaimResponseBundle |
| Success status | response.complete |
| Callback logic | Send the adjudicated preauthorization payload or send ProtocolResponse. |
10. Raise a Communication Request
| Item | Requirement |
|---|---|
| API to call | POST /v1/communication/request |
| Callback API to implement | POST /v1/communication/on_request |
| API owner | Provider |
| Request bundle | TaskBundle with CommunicationRequest |
| Request status | request.initiated |
| Callback logic | Receive the provider attachment response or a protocol error. |
11. Respond to a Claim
| Item | Requirement |
|---|---|
| API to receive | POST /v1/claim/submit |
| Callback API to call | POST /v1/claim/on_submit |
| Callback API owner | Provider |
| Success bundle | ClaimResponseBundle |
| Success status | response.complete or response.partial |
| Callback logic | Send the adjudicated claim payload or send ProtocolResponse. |
12. Respond to Search Request
| Item | Requirement |
|---|---|
| API to receive | POST /v1/search/submit |
| Callback API to call | POST /v1/search/on_submit |
| Callback API owner | Provider or regulator |
| Success bundle | TaskBundle with ClaimResponse output |
| Success status | response.partial or response.complete |
| Callback logic | Send claim response data for the requested task inputs. |
13. Send Payment Notice
| Item | Requirement |
|---|---|
| API to call | POST /v1/paymentnotice/request |
| Callback API to implement | POST /v1/paymentnotice/on_request |
| API owner | Provider |
| Request bundle | TaskBundle with PaymentNotice |
| Request status | request.initiated |
| Callback logic | Receive a payment acknowledgment task output. |
14. Respond to a Task Request
| Item | Requirement |
|---|---|
| API to receive | POST /v1/task/submit |
| Callback API to call | POST /v1/task/on_submit |
| Callback API owner | Provider |
| Success bundle | TaskBundle with ClaimResponse output |
| Success status | response.complete |
| Callback logic | Send a task response or send ProtocolResponse. |
15. Get Status
| Item | Requirement |
|---|---|
| API to call | POST /v1/status |
| Callback API to implement | POST /v1/on_status |
| API owner | NHCX |
| Request bundle | Empty payload |
| Success bundle | Protocol header only |
| Request status | request.initiated |
| Callback status | request.dispatched |
| Callback logic | Accept the status callback with all protocol header attributes. |
Sources
- payer-side-use-cases.md (NHCX sandbox portal)