EUA — Phase 5: Post-Fulfilment (Cancellation & Messaging)
Phase 5 covers two independent features: appointment cancellation and in-app messaging between patient and doctor.
Cancellation Flow
Messaging Flow
Patient → Doctor (text)
Doctor → Patient (prescription / media)
API Endpoints
POST /uhi/bookings/:order_id/cancel — Cancel appointment
Auth required: Yes (Kulcare JWT Bearer token)
Request body:
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"service_type": "physical",
"cancel_reason": "P1"
}The booking must belong to the signed-in patient; any other order_id gets 404. The cancellation goes out
under the booking's own transaction_id, and with cancelled_by: "patient": this is the patient's route, so a
cancelled_by in the request is ignored. That value fills the mandatory @abdm/gov.in/cancelledby tag in the
UHI spec, which the HSPA uses to decide which cancellation policy applies.
Response: { "success": true, "transaction_id": "txn-abc123" }
POST /uhi/messages — Send message
Auth required: Yes
Text message:
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"transaction_id": "txn-abc123",
"sender": { "id": "rahul@abdm", "name": "Rahul Sharma" },
"receiver": { "id": "drsmith@hpr.ndhm", "name": "Dr. Smith" },
"content": {
"value": "Hello Doctor, I have a follow-up question.",
"type": "text"
}
}transaction_id is required and must be one of the signed-in patient's bookings; any other gets 404.
Media message (e.g. lab report):
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"transaction_id": "txn-abc123",
"sender": { "id": "rahul@abdm", "name": "Rahul Sharma" },
"receiver": { "id": "drsmith@hpr.ndhm", "name": "Dr. Smith" },
"content": {
"value": "<raw binary bytes or base64 string>",
"type": "media",
"mime_type": "application/pdf",
"file_name": "lab_report.pdf",
"hi_type": "labReport"
}
}The service automatically Base64-encodes content.value before sending.
on_cancel Callback (Inbound)
Endpoint: POST /uhi/on_cancel
Caller: HSPA
{
"context": { "action": "on_cancel", "transaction_id": "txn-abc123" },
"message": {
"order": {
"id": "0415-234567-8901",
"state": "CANCELLED",
"fulfillment": {
"tags": { "@abdm/gov.in/cancelledby": "patient" }
},
"payment": { "status": "REFUND_INITIATED" }
}
}
}After receiving on_cancel, the controller automatically sends an audit copy to the UHI Gateway.
on_message Callback (Inbound)
Endpoint: POST /uhi/on_message
Caller: HSPA (doctor sending to patient)
Text message:
{
"context": { "action": "on_message" },
"message": {
"intent": {
"chat": {
"sender": { "person": { "id": "drsmith@hpr.ndhm", "name": "Dr. Smith" } },
"receiver": { "person": { "id": "rahul@abdm", "name": "Rahul Sharma" } },
"content": {
"content_id": "msg-123",
"content_value": "SGVsbG8sIHRha2UgdGhlc2UgbWVkaWNhdGlvbnMu",
"content_type": "text"
},
"time": { "timestamp": "2026-04-17T11:00:00Z" }
}
}
}
}Prescription (media):
{
"message": {
"intent": {
"chat": {
"content": {
"content_id": "msg-456",
"content_value": "<base64 PDF>",
"content_type": "media",
"content_mimeType": "pdf/application",
"content_fileName": "prescription.pdf",
"hiType": "prescription"
}
}
}
}
}Supported hiType Values
| hiType | Description |
|---|---|
prescription | Doctor prescription |
labReport | Laboratory test results |
opConsultation | Outpatient consultation note |
diagnosticReport | Imaging / diagnostic report |
immunizationRecord | Vaccination record |
healthDocumentRecord | General health document |
dischargeSummary | Hospital discharge summary |
Cancellation Policies
The HSPA applies different policies based on cancelled_by:
cancelled_by | Policy Applied |
|---|---|
patient | Patient cancellation terms (from on_init) |
doctor | Doctor cancellation terms — typically full refund |
The refund status in on_cancel.payment.status indicates the outcome:
| Payment Status | Meaning |
|---|---|
REFUND_INITIATED | Refund process started |
REFUNDED | Refund completed |
NO_REFUND | Cancellation policy waives refund |