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.

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.

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.

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:

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:

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

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.

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.

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.

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):

{
  "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.

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

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.

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

{
  "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:

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:

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:

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.

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"}'

{
  "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.

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.

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:

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:

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.

Patient shows the pass

The patient opens Apple Wallet or Google Wallet and shows the barcode.

You scan it

Your scanner reads wallet_pass_uid. Treat that value as a credential.

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.

Load profile details with GET /v1/management/patients after Verify. Pharmacy tablet OTP is documented under Tablet wallet pass and is not part of this SKU.

Patients API — Step 1: create or resolve the shop customer.
Management API Wallet Passes — Issue, list, verify, revoke.
Wallet Passes (Help Center) — What patients see on their phone.

​Patient Pass

​What RxScale provisions vs what you do

​Two-step issuance

​Identity-only vs prescription templates

​What Are Wallet Passes?

​Creating Wallet Passes

​Managing Wallet Passes via API

​Create or Update a Wallet Pass

​Get a Wallet Pass

​List Wallet Passes

​Delete a Wallet Pass

​Verify a Scanned Pass

​List Templates

​Send Push Notifications

​Automatic Refresh on Patient Profile Changes

​Push Notifications

​Verify a scanned Patient Pass

​Related Topics

Patient Pass

What RxScale provisions vs what you do

Two-step issuance

Identity-only vs prescription templates

What Are Wallet Passes?

Creating Wallet Passes

Managing Wallet Passes via API

Create or Update a Wallet Pass

Get a Wallet Pass

List Wallet Passes

Delete a Wallet Pass

Verify a Scanned Pass

List Templates

Send Push Notifications

Automatic Refresh on Patient Profile Changes

Push Notifications

Verify a scanned Patient Pass

Related Topics