> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay an open order with Scan and Pay

> Share the patient's profile from a facility QR code, fetch their open orders, get a payment link for the selected ones, and read the transaction result.

## 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](https://developer.eka.care/api-sdk/auth/getting-started.md).
* 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](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md). 
* The `hip_id` and `counter_id` read from the facility's QR code. 

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient on payment page
  App->>Eka: POST /abdm/v1/profile/scan-and-pay/open-order
  App->>Eka: GET /abdm/v1/profile/scan-and-pay/open-order/{request_id}
  App->>Eka: POST /abdm/v1/profile/scan-and-pay/patient-select
  App->>Eka: GET /abdm/v1/profile/scan-and-pay/patient-select/{request_id}
  App-->>Patient: open payment_url
  App->>Eka: GET /abdm/v1/profile/scan-and-pay/transaction-details/{request_id}
```

## 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](https://developer.eka.care/api-sdk/uhi/scan-and-pay/open-orders.md). 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](https://developer.eka.care/api-sdk/uhi/scan-and-pay/get-open-orders.md) 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](https://developer.eka.care/api-sdk/uhi/scan-and-pay/patient-select.md). 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](https://developer.eka.care/api-sdk/uhi/scan-and-pay/get-patient-select.md) 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](https://developer.eka.care/api-sdk/uhi/scan-and-pay/get-transaction-details.md) 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

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA login | On the patient record | `X-Pt-Id` header on every call |
| `hip_id`, `counter_id` | Facility QR code | Until the payment completes | Open Orders |
| `request_id` | Open Orders | Until the transaction details are final | Get Open Orders, Patient Select, and possibly Get Transaction Details |
| `request_id` | Patient Select | Until the transaction details are final | Get Patient Select Details |
| `order_number`, `amount` | Get Patient Select Details | With the payment record | Matching the payment to the facility's order |
| `transactionId`, `paymentReceiptLink` | Get Transaction Details | With the payment record | Showing the receipt later |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md), 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](https://developer.eka.care/docs/hie-cm/errors.md).

| Situation | Code | Do |
| - | - | - |
| Missing `hip_id` or `counter_id`, or an unreadable QR | 4XX | Ask the patient to scan again |
| Unknown or invalid `request_id` | `ABDM-1030` (expected, not confirmed) | Restart from Open Orders |
| Facility does not answer | `ABDM-1028` or `ABDM-1401` (expected, not confirmed) | Tell the patient to pay at the counter |
| Facility answers with an error | `status` `ERROR`, `data.error.code` | Show `data.error.message`; pay at the counter |
| Payment fails or is abandoned | Transaction details `data.status` | |
| Rate limit | `ABDM-1022` (expected, not confirmed) | |

## Test it

The [testing page](https://developer.eka.care/docs/hie-cm/testing.md) 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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.