Overview
Passinstance automates the lifecycle of digital passes across design, cryptographic packaging, multichannel distribution, point-of-sale validation, and silent push synchronization. By separating visual layout configuration from business logic mechanics and device communication protocols, the platform delivers a uniform experience across both iOS and Android ecosystems.
End-to-End Technical Sequence
The following sequence diagram details the end-to-end flow from template creation to real-time wallet synchronization:
Step-by-Step Technical Lifecycle
1. Template Authoring & Versioning
Every pass originates from a Template record. Passinstance uses single-table versioning tracked by TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) and template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED). Draft edits stay isolated in a DRAFT revision until an operator or API caller executes POST /api/v1/templates/:id/publish, which promotes the draft into the canonical PRODUCTION base row and preserves immutable PUBLISHED / ARCHIVED history snapshots. Before publishing, the platform evaluates GET /api/v1/templates/:id/publish-risk-check to inspect critical field changes and calculate how many live passes will be updated.
2. Cryptographic Signing, Artifact State & Pass Issuance
When a pass record is generated (POST /api/v1/passes), pass creation resolves templateId via resolvePassCreationTemplateId to the live base row, binds an optional tenant-unique externalId, honors the optional Idempotency-Key header (idempotencyKey), and initializes appleArtifactStatus and googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):
-
Apple Wallet: On download,
Apple Wallet Packagerbundlespass.json, up to 13 image slots (image asset slot including@2xand@3xretina variants), and localizedpass.stringsinto a.pkpasszip archive, computesmanifest.jsonhashes, and signs the manifest via detached PKCS#7 encryption with your Apple Pass Type ID and Apple WWDR certificates. Multiple companion passes sharing abundleId(Pass.bundleId) can be delivered together as a.pkpassesarchive. -
Google Wallet: The backend syncs class definitions (
LoyaltyClass,EventTicketClass,GenericClass, etc.) with Google Wallet REST APIs and signs aRS256JWT Save URL (https://pay.google.com/gp/v/save/:jwt).
3. Smart Link Distribution
Passinstance issues canonical smart presentation URLs (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId, or /s/:token on API/vanity hosts). When accessed by an end user:
-
Public Download Endpoint (
GET /d/:slug/download) detects the user agent:
- iOS Safari receives an HTTP response with MIME type application/vnd.apple.pkpass, opening the native Apple Wallet add sheet. - Android Chrome is redirected to https://pay.google.com/gp/v/save/:jwt, launching Google Wallet. - Desktop browsers render the PassFlow download page with a high-contrast QR code (GET /d/:slug/qr) and optional email/SMS self-delivery.
4. Device Registration & Web Service Handshake
Upon saving to Apple Wallet, the iOS device initiates the official Apple Wallet Web Service protocol:
-
It issues
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberwith the headerAuthorization: ApplePass <authenticationToken>. -
Passinstance validates the token and records the device's
pushTokenin the database, transitioning the pass status fromAWAITING_OPT_INtoACTIVE.
5. Point-of-Sale Validation & Mechanics Execution
At physical checkout or venue check-in, an operator scans the pass using the Passinstance Scanner app or an integrated POS system:
-
A request is dispatched to
POST /api/v1/scansauthenticated viax-scanner-key. -
The
Pass Mechanics Engineevaluates active rules (e.g., adding stamps, deducting prepaid currency, validating single-use coupons, or verifying once-per-day attendance).
6. Silent Cloud Push Synchronization
When pass data changes:
-
Passinstance dispatches an empty JSON payload
{}over HTTP/2 to Apple APNs servers. -
The Apple device wakes silently in the background, queries
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, and downloads the updated.pkpassbundle. -
Any field configured with a
changeMessagecontaining the placeholder%@generates a native iOS lock-screen notification. -
Concurrently, Passinstance sends a REST
PATCHrequest to the Google Walletwalletobjectsendpoint, updating the Android card in real time.

Core API Endpoints & Verbs
| Endpoint Path | HTTP Method | Authentication | Functionality |
|---|---|---|---|
/api/v1/templates | POST | Bearer / API Key | Create a new pass template definition |
/api/v1/templates/:id/publish | POST | Bearer / API Key | Promote draft template to live production version |
/api/v1/passes | POST | Bearer / API Key | Issue a new pass with custom field values |
/api/v1/passes/:id | PATCH | Bearer / API Key | Update existing pass attributes and enqueue push |
/api/v1/scans | POST | x-scanner-key | Validate pass barcode, apply mechanic, record scan |
/v1/devices/... | POST | ApplePass <token> | Apple Wallet device registration callback |
Important: Apple Wallet updates are pull-based: Passinstance does not send pass data inside the APNs notification. Instead, an empty APNs wake-up signal instructs the Apple device to securely pull the latest signed
.pkpassfrom Passinstance servers.
Explore the complete 6-phase onboarding guide or review our API Architecture.
