EUA — Phase 3: Booking (init & confirm)
The Booking phase is a two-step P2P flow directly between Kulcare (EUA) and the chosen HSPA. All calls go to the provider_uri obtained from the on_search catalog — not through the Gateway.
Full Booking Flow
Step 1: POST /uhi/bookings/init
Auth required: Yes (Kulcare JWT Bearer token)
Sends the selected slot, patient details, and payment type to the HSPA.
Request body:
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"transaction_id": "txn-abc123",
"service_type": "physical",
"order": {
"provider": { "id": "1" },
"item": {
"id": "0",
"descriptor": { "name": "Consultation", "code": "Consultation" },
"price": { "currency": "INR", "value": "500.0" },
"fulfillment_id": "slot-uuid-abc"
},
"fulfillment": {
"id": "slot-uuid-abc",
"type": "Physical",
"agent": { "id": "drsmith@hpr.ndhm", "name": "Dr. Smith" },
"start": { "time": { "timestamp": "2026-04-17T10:00:00" } },
"end": { "time": { "timestamp": "2026-04-17T10:20:00" } }
},
"billing": {
"name": "Rahul Sharma",
"address": { "locality": "Lajpat Nagar", "city": "Delhi", "state": "Delhi", "country": "INDIA", "area_code": "110024" },
"phone": "9876543210",
"email": "rahul@example.com"
},
"customer": {
"id": "rahul@abdm",
"person": { "gender": "M", "dob": "1990-01-01" }
},
"payment": { "type": "ON-ORDER" }
}
}Response: { "success": true, "transaction_id": "txn-abc123" }
Returns immediately. The HSPA sends T&C via on_init asynchronously (within seconds).
on_init Callback (Inbound)
Endpoint: POST /uhi/on_init
Caller: HSPA
The HSPA responds with an order ID and five mandatory term types. All five must be sent back with termsState: "AGREED" in /confirm.
{
"context": { "action": "on_init", "transaction_id": "txn-abc123" },
"message": {
"order": {
"id": "0415-234567-8901",
"terms": [
{ "type": "Commercial", "descriptor": { "name": "Commercial Terms" }, "termsState": "INITIATED" },
{ "type": "Cancellation", "descriptor": { "name": "Cancellation Policy" }, "termsState": "INITIATED", "reasonRequired": true },
{ "type": "Refund", "descriptor": { "name": "Refund Policy" }, "termsState": "INITIATED" },
{ "type": "Payment", "descriptor": { "name": "Payment Terms" }, "termsState": "INITIATED" },
{ "type": "Settlement", "descriptor": { "name": "Settlement Terms" }, "termsState": "INITIATED" }
],
"quote": { "price": { "currency": "INR", "value": "500.0" } },
"payment": { "type": "ON-ORDER", "status": "NOT_PAID" }
}
}
}Five Term Types
| Type | Description | reasonRequired |
|---|---|---|
Commercial | Fee structure and payment terms | No |
Cancellation | Cancellation window and penalty | Yes |
Refund | Refund eligibility and timeline | No |
Payment | Payment method and timing | No |
Settlement | Provider settlement terms | No |
Step 2: POST /uhi/bookings/confirm
Auth required: Yes (Kulcare JWT Bearer token)
Sends confirmation with all five terms set to AGREED.
Request body:
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"transaction_id": "txn-abc123",
"order": {
"id": "0415-234567-8901",
"terms": [
{ "type": "Commercial", "termsState": "AGREED" },
{ "type": "Cancellation", "termsState": "AGREED" },
{ "type": "Refund", "termsState": "AGREED" },
{ "type": "Payment", "termsState": "AGREED" },
{ "type": "Settlement", "termsState": "AGREED" }
],
"provider": { "id": "1" },
"item": { "id": "0", "fulfillment_id": "slot-uuid-abc" },
"fulfillment": { "id": "slot-uuid-abc", "type": "Physical" },
"billing": { "name": "Rahul Sharma", "phone": "9876543210", "email": "rahul@example.com" },
"customer": { "id": "rahul@abdm" },
"payment": { "type": "ON-ORDER" }
}
}Important: All five terms from
on_initmust be echoed back with"termsState": "AGREED". Missing terms will cause the HSPA to reject the confirmation.
Response: { "success": true, "transaction_id": "txn-abc123" }
on_confirm Callback (Inbound)
Endpoint: POST /uhi/on_confirm
Caller: HSPA
On receiving confirmation, the HSPA sends a 4-digit PIN the patient uses at check-in.
{
"context": { "action": "on_confirm", "transaction_id": "txn-abc123" },
"message": {
"order": {
"id": "0415-234567-8901",
"state": "CONFIRMED",
"authorization": {
"type": "PIN",
"token": "7342",
"valid_from": "2026-04-17T00:00:00",
"valid_to": "2026-04-17T23:59:00",
"status": "GENERATED"
}
}
}
}PIN Lifecycle
| Status | Meaning |
|---|---|
GENERATED | Booking confirmed, PIN issued |
VERIFIED | Patient checked in (HSPA scanned PIN) |
NOT_VERIFIED | Appointment time passed, PIN not used |
HSPA_OVERRIDE | Doctor started without scanning PIN |
Audit to Gateway
OnConfirmController automatically calls AuditService#send_on_confirm_audit to forward the on_confirm payload to the UHI Gateway for compliance logging.
Slot Timeout
The HSPA holds the slot for approximately 15 minutes after /init. If /confirm is not received within that window, the slot is released and the booking must be restarted from /init.
Error Cases
| Scenario | HSPA Response |
|---|---|
| Slot no longer available | on_init with error message |
| Terms not all AGREED | NACK or error in on_confirm |
| Patient ABHA ID invalid | on_init with validation error |
| Payment type not supported | on_init with error |