Wallet Passes

Wallet passes are digital cards that patients carry on their phones for identity verification. This page explains how telemedicine providers can use wallet passes in their workflow.

What Are Wallet Passes?

A wallet pass is a digital card stored in a patient’s Apple Wallet or Google Wallet app. It contains a QR code that can be scanned to verify the patient’s identity. Think of it as a digital membership card that is always available on the patient’s phone. Wallet passes are useful for:

Patient verification — Confirming a patient’s identity at a pharmacy or during a consultation.
Quick identification — Allowing staff to look up a patient’s information by scanning their QR code.
Push notifications — Sending updates to patients directly through their wallet 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.

Patient Verification via QR Code

The QR code on a wallet pass enables a secure identity verification process:

Patient shows their wallet pass

The patient opens their wallet app and displays the QR code on their pass.

Staff scans the QR code

A pharmacy staff member or other authorised person scans the QR code using the RxScale system.

OTP verification

The system sends a one-time password (OTP) to the patient’s email address, and also by SMS to the phone number registered in their patient profile when one is on file.

Identity confirmed

The patient provides the OTP to the staff member. Once verified, the patient’s identity is confirmed.

This two-step verification (QR code plus OTP) ensures that only the actual patient can complete the verification, even if someone else has a copy of the QR code.

Wallet Passes (Help Center) — General information about how wallet passes work.
Management API Wallet Passes — API reference for wallet pass endpoints.

​Wallet Passes

​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

​Patient Verification via QR Code

​Related Topics

Wallet Passes

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

Patient Verification via QR Code

Related Topics