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

# Patient Pass

> Issue an identity-in-wallet Patient Pass and verify it with the Management API

# Patient Pass

**Patient Pass** is the commercial offering: a digital card in the patient's Apple Wallet or Google Wallet that proves who they are. Scan the barcode, call Verify, and you get shop-scoped identity handles back.

API paths stay named `/wallet-passes`. That is the implementation name. When you talk to customers or ops, call the product Patient Pass.

<Warning>
  Patient Pass is **not** the pharmacy tablet OTP flow. Tablet QR-plus-OTP lives in the pharmacy tool and is a different product. This page only covers Management API issuance and `POST /wallet-passes/verify`.
</Warning>

## What RxScale provisions vs what you do

RxScale sets up the organisation, the shop, an API key (`patient:write`, `wallet_pass:write`, `wallet_pass:verify`), and the Patient Pass template.

You create the patient in that shop, issue the pass, send the download links, and verify scans. You do not design the pass or mint API keys.

## Two-step issuance

The patient must already be a customer of the shop (`shop_customer_id` on that shop). Create or resolve them first, then issue the pass.

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/patients" \
  -H "X-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_uid": "shop_123",
    "shop_customer_id": "cust-123",
    "email": "max@example.com"
  }'
```

Then:

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/wallet-passes" \
  -H "X-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_pass_template_uid": "wpt-abc123",
    "shop_customer_id": "cust-123",
    "shop_identifier": "my-shop"
  }'
```

A patient that is not a customer of the chosen shop is rejected. Do not skip step 1.

## Identity-only vs prescription templates

New templates require a signed prescription unless ops marks the template as identity-only.

* **Prescription templates** -- issued after the patient has a signed prescription. SKU-mapped templates issue automatically when the prescription is signed.
* **Identity-only templates** -- issued earlier, with no prescription on the card. This is an explicit opt-in on the template.

## What Are Wallet Passes?

A wallet pass is the digital card behind Patient Pass. It lives in Apple Wallet or Google Wallet and carries a barcode you scan to verify identity.

Uses:

* **Patient verification** -- Confirm who is standing in front of you via Verify, not via pharmacy-tablet OTP.
* **Quick identification** -- Resolve a scan to `patient_profile_uid` and `shop_customer_id`.
* **Push notifications** -- Send updates through the pass.

## Creating Wallet Passes

You can create wallet passes for your patients using the Management API. When you create a wallet pass:

1. The system generates a unique wallet pass for the patient.
2. The patient receives a link to add the pass to their phone.
3. Once added, the pass is stored in their Apple Wallet or Google Wallet.

<Info>
  Patients need to actively add the pass to their phone. The pass is not installed automatically -- they will receive a link and need to tap it to add it.
</Info>

<Note>
  Pass content is defined by the wallet pass template. When mapped, RxScale fills the
  patient's date of birth and the date of their first signed or non-QES-signed
  prescription (patient since), in addition to name and latest-prescription fields.
</Note>

## Managing Wallet Passes via API

The Management API provides full CRUD access for wallet passes. All endpoints require an API key with the appropriate permissions (`wallet_pass:read`, `wallet_pass:write`).

### Create or Update a Wallet Pass

Use the create endpoint to issue a new wallet pass for a patient. If a wallet pass already exists for the same template and patient, it will be updated instead of creating a duplicate.

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/wallet-passes" \
  -H "X-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_pass_template_uid": "wpt-abc123",
    "shop_customer_id": "cust-123",
    "shop_identifier": "my-shop"
  }'
```

**Response** (`201 Created` for new passes, `200 OK` for updates):

```json theme={null}
{
  "uid": "wp-abc123",
  "wallet_pass_template_uid": "wpt-abc123",
  "external_id": "ext-123",
  "serial_number": "SN-123",
  "ios_download_url": "https://...",
  "android_download_url": "https://...",
  "patient_profile_uid": "pp-abc123",
  "created_at": 1712000000
}
```

The response includes download URLs for both iOS and Android. Share these links with your patient so they can add the pass to their phone.

<Info>
  The create endpoint uses **upsert** semantics. You can safely call it multiple times for the same patient and template without creating duplicate passes.
</Info>

<Note>
  Templates that display prescription details are issued after the patient has a signed
  prescription. Identity-only templates can be issued earlier. In the admin tool under
  **Settings → Wallet passes**, you can mark a template so it still waits for a signed prescription
  even when it does not display prescription details.
</Note>

When issuance is deferred for this reason, the create call returns `400` with a specific message
rather than a generic error:

```json theme={null}
{
  "error": "The wallet pass template requires a signed prescription, but this patient has none."
}
```

This is a retryable state, not a failure of your request. Call the endpoint again once the patient
has a signed prescription; the upsert semantics above make the retry safe. For templates mapped to
a SKU, the pass is issued automatically when the prescription is signed, so no retry is needed.

### Get a Wallet Pass

Retrieve details for a specific wallet pass by its UID:

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/wallet-passes/{wallet_pass_uid}" \
  -H "X-API-Key: {api_key}"
```

### List Wallet Passes

List all wallet passes for a specific customer:

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/wallet-passes?shop_customer_id=cust-123&shop_identifier=my-shop" \
  -H "X-API-Key: {api_key}"
```

You can optionally filter by template using the `wallet_pass_template_uid` query parameter.

### Delete a Wallet Pass

Revoke a wallet pass when it is no longer needed:

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/wallet-passes/{wallet_pass_uid}" \
  -H "X-API-Key: {api_key}"
```

Returns `204 No Content` on success. The pass is removed from the external wallet pass provider and will no longer be valid on the patient's phone.

### Verify a Scanned Pass

Scanning a Patient Pass yields its `wallet_pass_uid`. Post it to resolve the pass to the patient behind it. Requires an API key with the `wallet_pass:verify` permission.

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/wallet-passes/verify" \
  -H "X-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"wallet_pass_uid": "3f9a1c2e-7b04-4c11-9f3d-2a8e5b6c0d17"}'
```

```json theme={null}
{
  "valid": true,
  "status": "active",
  "wallet_pass_uid": "3f9a1c2e-7b04-4c11-9f3d-2a8e5b6c0d17",
  "patient_profile_uid": "b21d4f8a-5c33-4e90-8a72-1f6b9d0c4e55",
  "shop_customer_id": "cust-123"
}
```

A revoked pass returns `"valid": false` with `"status": "revoked"`, so you can tell a cancelled pass from one that is not yours. A pass belonging to another organisation returns `404`, exactly like an unknown value.

<Warning>
  Treat the `wallet_pass_uid` as a credential -- anyone holding it can resolve the patient behind the pass. Send it in the request body, never in a URL, and do not write it to logs.
</Warning>

This endpoint returns identity handles only. Load the patient's details with `GET /v1/management/patients`.

### List Templates

List available wallet pass templates for a shop:

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/wallet-passes/templates?shop_identifier=my-shop" \
  -H "X-API-Key: {api_key}"
```

### Send Push Notifications

Send push notifications to patients through their wallet passes:

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/wallet-passes/push-notifications" \
  -H "X-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "wallet_pass_uid": "wp-abc123",
      "message": "Your prescription has been signed."
    }
  ]'
```

When you update a pass, the changes are automatically pushed to the patient's phone. They do not need to take any action to see the updated information.

### Automatic Refresh on Patient Profile Changes

When a patient's profile is updated (e.g. name change after marriage), all existing wallet passes for that patient are automatically refreshed. The updated data is pushed to the wallet pass provider so the patient's pass always shows current information.

## Push Notifications

One of the most powerful features of wallet passes is the ability to send push notifications to patients. When a patient has your wallet pass on their phone, you can send them notifications that appear on their lock screen.

Common uses for push notifications:

* Notifying patients that their prescription has been signed.
* Alerting patients that their order has shipped.
* Reminding patients about upcoming consultations.

Push notifications are sent through the wallet pass platform, so patients receive them even if they are not actively using your app.

## Verify a scanned Patient Pass

The barcode encodes `wallet_pass_uid`. Post it to Verify. You get identity handles, not a pharmacy OTP challenge.

<Steps>
  <Step title="Patient shows the pass">
    The patient opens Apple Wallet or Google Wallet and shows the barcode.
  </Step>

  <Step title="You scan it">
    Your scanner reads `wallet_pass_uid`. Treat that value as a credential.
  </Step>

  <Step title="Call Verify">
    `POST /v1/management/wallet-passes/verify` with the UID in the body. You receive `patient_profile_uid` and `shop_customer_id` when the pass is yours and active.
  </Step>
</Steps>

Load profile details with `GET /v1/management/patients` after Verify. Pharmacy tablet OTP is documented under [Tablet wallet pass](/for-pharmacists/tablet-wallet-pass) and is not part of this SKU.

## Related Topics

* [Patients API](/api-reference/management/patients) -- Step 1: create or resolve the shop customer.
* [Management API Wallet Passes](/api-reference/management/wallet-passes) -- Issue, list, verify, revoke.
* [Wallet Passes (Help Center)](/help-center/wallet-passes) -- What patients see on their phone.


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