Skip to main content

​
In short

  • Share the profile, list open orders, get a payment link, then read the payment result.
  • Each POST returns a request_id; poll the matching GET with it, since no webhook is documented.
  • The patient pays on payment_url; no Scan and Pay operation takes the payment.

​
When to use this

The patient has scanned a facility’s Scan and Pay QR code in your Personal Health Record (PHR) app and wants to pay an open bill. This workflow:
  • shares the patient’s profile with the facility
  • lists their open orders
  • gets a payment link for the ones they select
  • reads the payment result.
Each POST returns a request_id and a status at once. You pass that request_id to the matching GET to read the result. No webhook is documented for Scan and Pay, so you poll.

​
Before you start

  • A Bearer token. Every Scan and Pay operation uses the authApiKey scheme. See Authorization.
  • The patient logged in on your app, with their Eka user id (oid) to send as X-Pt-Id. See Log in to an existing ABHA.
  • The hip_id and counter_id read from the facility’s QR code.

​
Sequence

​
Steps

All five operations return a status from the same list: REQUESTED_OPEN_ORDER, PROCESSING_OPEN_ORDER, REQUESTED_PATIENT_SELECT, PROCESSING_PATIENT_SELECT, PROCESSING_PATIENT_NOTIFY, REQUESTING_PATIENT_NOTIFY and ERROR.
1

Share the profile and request open orders

Send hip_id and counter_id from the QR code to Open Orders. This shares the patient’s profile with the facility. Keep request_id from the response. status is REQUESTED_OPEN_ORDER.
2

Read the open orders

Call Get Open Orders with request_id. When the facility has answered, data carries abha_address, intent and procedures. Each procedure has a category and services, each with serviceId, name, description and amount.If status is ERROR, read data.error.code and data.error.message. If procedures is empty, the patient has nothing to pay here. The patient selects what to pay.
3

Select the orders to pay

Send request_id from step 1, intent set to PAYMENT_ORDER, and the selected procedures to Patient Select. All three are required. The spec describes this call as returning the payment link for the selected order. Keep request_id from the response.
4

Read the payment link

Call Get Patient Select Details with request_id. data.payment_bundle carries payment_url, amount, order_number, merchant_id, payment_mode and description. Show amount and open payment_url for the patient. The patient pays on that page; no Scan and Pay operation takes the payment.
5

Read the transaction details

Call Get Transaction Details with request_id. data carries status, transactionId, orderNumber, paymentDate, paymentReceiptLink, abhaAddress and openOrderRequestId. Show the status and the receipt link to the patient.

​
State you must persist

​
When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, matched by meaning. Log the code you actually receive.
Every operation returns GenericError with code, error and source_error on a 4XX or 5XX. A failure inside the facility’s answer comes back as status ERROR with data.error. See Errors.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey.
  • Open Orders with a test hip_id and counter_id; receive a request_id and REQUESTED_OPEN_ORDER
  • Get Open Orders until procedures is returned
  • Patient Select with one procedure and PAYMENT_ORDER; Get Patient Select Details returns payment_url
  • Complete the payment on payment_url with sandbox payment details
  • Get Transaction Details returns a transactionId and paymentReceiptLink
  • Failure: Get Open Orders with an unknown request_id
  • Failure: a counter_id with no open orders returns empty procedures