Wallet passes

Orbit can issue digital passes for Apple Wallet and Google Wallet: loyalty cards, coupons, and event tickets your customers save to the wallet app on their phone. Issue them through the API or from the dashboard’s issuance builder, and deliver them by putting the pass’s save link in any message you send — SMS, WhatsApp, or email. Three pass types are supported today:

Loyalty cards — points balance, tier, or membership number behind a scannable barcode.
Coupons — an offer with a redemption barcode and an optional expiry date.
Event tickets — a ticket with seat, gate, or order details.

The pass lifecycle

Every pass moves through the same lifecycle:

Issue — POST /wallet-passes/issue creates the pass and returns both platform payloads (an Apple pass.json structure and a Google “Save to Wallet” link). New passes start active.
Update — POST /wallet-passes/:id/update patches an active pass’s content (points balance, tier, coupon expiry, ticket seat). Each accepted update bumps the pass’s generation counter, which is the signal that the holder should refresh the pass on their phone.
Void — POST /wallet-passes/:id/void permanently revokes an active pass. Voiding is terminal: a voided pass reports status: "voided" and rejects any further update or re-void with a 409 CONFLICT error.

Request body (issue):

Field	Type	Description
`type`	string (required)	`loyalty_card`, `coupon`, or `ticket`.
`contact_id`	string	Orbit contact this pass is issued to.
`external_id`	string	Your own correlation reference (order id, ticket id, membership id).
`title`	string (required)	Main pass heading.
`subtitle`	string	Secondary line under the title.
`description`	string	Pass description shown on the back/details view.
`organization_name`	string	Issuing organization; defaults to `Orbit`.
`barcode_message`	string	Value encoded in the barcode.
`barcode_format`	string	`QR_CODE` (default), `PDF_417`, `AZTEC`, or `CODE_128`.
`background_color` / `foreground_color` / `label_color`	string	`#RRGGBB` hex colors; omitted values use the platform default styling.
`fields`	array	Up to 20 label/value rows (`key`, `label`, `value`) rendered on the pass.
`expires_at`	ISO datetime	When the pass stops being valid.
`metadata`	object	Free-form extra data stored with the pass.
`idempotency_key`	string	Retries with the same key return the first issued pass instead of minting a duplicate.

Issuing a pass

curl -X POST https://api.orbit.devotel.io/api/v1/wallet-passes/issue \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "loyalty_card",
    "contact_id": "ctn_9f8e7d6c5b4a",
    "title": "Aurora Coffee Rewards",
    "subtitle": "Gold tier",
    "organization_name": "Aurora Coffee",
    "barcode_message": "MEMBER-10482",
    "barcode_format": "QR_CODE",
    "background_color": "#1E3FB0",
    "fields": [
      { "key": "points", "label": "Points", "value": "1,240" },
      { "key": "member_since", "label": "Member since", "value": "2024" }
    ],
    "idempotency_key": "enroll-10482-2026-08"
  }'

Response

{
  "data": {
    "id": "wps_a1b2c3d4e5f6g7h8a1b2c3d4e5f6g7h8",
    "type": "loyalty_card",
    "status": "active",
    "generation": 0,
    "platforms": {
      "apple": {
        "configured": true,
        "reason": null,
        "pass_json": { "formatVersion": 1, "serialNumber": "wps_a1b2c3..." }
      },
      "google": {
        "configured": true,
        "reason": null,
        "object": { "id": "3388000000000000.wps_a1b2c3...", "state": "ACTIVE" },
        "save_url": "https://pay.google.com/gp/v/save/eyJhbGciOi..."
      }
    }
  }
}

Issuing is idempotent: pass an idempotency_key (or an Idempotency-Key header) and a retry returns the original pass with replayed: true instead of minting a second one. The replayed response reflects the pass’s current state — so a delayed retry after an update or void never reports stale content.

Platform status

Before issuing, check which platforms are live:

curl https://api.orbit.devotel.io/api/v1/wallet-passes/platforms \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "apple": { "configured": false, "reason": "apple_wallet_credentials_not_configured" },
    "google": { "configured": true, "reason": null },
    "types": ["loyalty_card", "coupon", "ticket"],
    "barcode_formats": ["QR_CODE", "PDF_417", "AZTEC", "CODE_128"]
  }
}

apple — configured: true when the Apple Wallet pass-type id and team id are connected. Until then pass_json is null, because there is no valid certificate identity to stamp the pass with.
google — configured: true when the Google Wallet issuer id and service-account credentials are connected. Until then save_url is null.
types / barcode_formats — the enums the issuance form can offer; use these to drive your own UI validation.

You can issue and manage passes with no platform connected — the pass content is stored and readable — but the downloadable payloads appear only after the matching platform is connected. Every read rebuilds the platform payloads fresh, so existing passes start producing working save links the moment credentials are connected; you never need to re-issue.

Signed issuance links

Each platform has its own signing mechanism:

Apple Wallet builds the pass as a signed .pkpass bundle: a PKCS#7 signature over a manifest of the pass files, using the Apple-issued pass signing certificate tied to your pass type. Orbit generates the unsigned pass.json content (platforms.apple.pass_json); the final binary signing step runs on the transport that holds the certificate material, once the Apple credentials are connected.
Google Wallet builds a signed “Save to Google Wallet” link (platforms.google.save_url): the pass is wrapped in a Google generic object and encoded as an RS256-signed token appended to https://pay.google.com/gp/v/save/.... Opening that link on an Android device or in a browser adds the pass to the holder’s Google Wallet account.

Listing, updating, and voiding passes

List issued passes (newest first) with optional filters:

curl "https://api.orbit.devotel.io/api/v1/wallet-passes?type=loyalty_card&status=active&limit=50" \
  -H "X-API-Key: dv_live_sk_..."

Update an active pass’s content — only the fields you send change; everything else carries forward:

curl -X POST https://api.orbit.devotel.io/api/v1/wallet-passes/wps_.../update \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subtitle": "Platinum tier",
    "fields": [
      { "key": "points", "label": "Points", "value": "2,015" }
    ]
  }'

Each update increments generation. To clear a field, send it as explicit null. Void a pass (optionally with a reason):

curl -X POST https://api.orbit.devotel.io/api/v1/wallet-passes/wps_.../void \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Membership cancelled" }'

A voided pass keeps its content for audit, reports status: "voided", renders as expired in the wallet, and cannot be updated.

Example: enroll a loyalty pass from an SMS deep link

The most common onboarding flow: a customer joins your loyalty program, and you text them their wallet pass.

Issue the pass tied to the enrolling contact:

curl -X POST https://api.orbit.devotel.io/api/v1/wallet-passes/issue \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "loyalty_card",
    "contact_id": "ctn_...",
    "title": "Aurora Coffee Rewards",
    "barcode_message": "MEMBER-10482",
    "idempotency_key": "enrollment-10482"
  }'

Pick the save link from the response — data.platforms.google.save_url for Google Wallet holders (the Apple Wallet equivalent is the signed pass the .pkpass transport serves once Apple credentials are connected).

Send the link over SMS using the standard messaging endpoint:

curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "channel": "sms",
    "content": {
      "text": "Welcome to Aurora Rewards! Add your card to your phone wallet: https://pay.google.com/gp/v/save/eyJ..."
    }
  }'

Keep the message brand-clean — save links are long, so route them through Orbit link shortening if you want a short URL. The same deep-link pattern works on SMS, WhatsApp, or email; pick whichever channel the customer opted into.

The dashboard issuance builder

Operators can run the whole lifecycle without the API. In the dashboard, open Marketing → Wallet passes (also reachable at Outbound → Wallet passes). The surface is gated to owner, admin, and developer roles.

Issue a pass — the New pass form offers exactly the pass types and barcode formats GET /wallet-passes/platforms reports, and flags when a platform is not yet connected.
Update content — edit points, tiers, or other fields on an active pass; each accepted edit bumps the pass generation.
Void a pass — revoke through a confirmation dialog; voided passes remain visible in the list for audit.
Copy save links — copy the Google save link (or read the Apple payload status) to drop into a message.

The dashboard surface and the API operate on one shared ledger, so a pass issued from the dashboard is visible to the API and vice versa.

How issuance state is stored

Wallet-pass state lives as events in the same append-only customer-data ledger that powers loyalty programs and incentive issuance. Issuing appends an issuance event; updates and voids append overlay events; and the current state of a pass is folded from its event stream on every read. There is no separate wallet-passes table to migrate, and nothing external to keep in sync — which is also what makes idempotent replays safe: the replayed response folds to the pass’s current lifecycle state. All wallet-pass endpoints are scoped with contacts:read (list/get/platforms) and contacts:write (issue/update/void) — a pass is customer-facing collateral tied to a contact.

Common errors

Code	HTTP	Cause	Fix
`VALIDATION_ERROR`	422	A field failed validation — bad hex color, unknown `type`/`barcode_format`, or more than 20 `fields`.	Check `details` in the response envelope for the offending field.
`NOT_FOUND`	404	The pass id is not a valid wallet-pass id (`wps_` + 32 hex), or no such pass exists.	Re-fetch from `GET /wallet-passes` and use the exact `id`.
`CONFLICT`	409	The pass is already voided and cannot be updated or voided again.	Treat void as terminal; issue a replacement pass if needed.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Issue Apple and Google Wallet passes

Wallet passes

The pass lifecycle

Issuing a pass

Response

Platform status

Signed issuance links

Listing, updating, and voiding passes

Example: enroll a loyalty pass from an SMS deep link

The dashboard issuance builder

How issuance state is stored

Common errors

​Wallet passes

​The pass lifecycle

​Issuing a pass

​Response

​Platform status

​Signed issuance links

​Listing, updating, and voiding passes

​Example: enroll a loyalty pass from an SMS deep link

​The dashboard issuance builder

​How issuance state is stored

​Common errors

Wallet passes

The pass lifecycle

Issuing a pass

Response

Platform status

Signed issuance links

Listing, updating, and voiding passes

Example: enroll a loyalty pass from an SMS deep link

The dashboard issuance builder

How issuance state is stored

Common errors