Skip to content
Help Center Guide · Introduction to PassinstanceOnboarding Phase 1
4 min readVerified 2026-11-16

How Passinstance Works

Follow the end-to-end architecture from template authoring and wallet signing to scanning, push updates, and analytics.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Workspace Dashboard — Live KPIs & Registration Trends (Zoomed)

Once your workflow is live, monitor Active in Wallets, Removed from Wallets, Not Installed, Pass Creation Trend, and Wallet Registration Trend from the main Dashboard.

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:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
END-TO-END PASS LIFECYCLE
PARTICIPATING SYSTEM ACTORS
P1 Admin / API Client
P2 Passinstance Core API
P3 Apple / Google Cloud
P4 Customer Device
STEP 1 REQUEST / ACTION POST/api/v1/templates
›
(Define Layout & Mechanics)
STEP 2 REQUEST / ACTION POST/api/v1/passes
STEP 3 REQUEST / ACTION Sign .pkpass (PKCS#7)
STEP 4 REQUEST / ACTION Generate Google JWT
›
Returns Download URL
›
(https://app.passinstance.com/d/:slug or /p/:passId)
STEP 5 REQUEST / ACTION Customer Opens Smart Download Link
›
(Browser Detects OS)
STEP 6 RESPONSE Device Registers (POST/v1/devices)
›
(Apple pushToken stored in Passinstance database)
STEP 7 REQUEST / ACTION Counter Scan at POS (POST/api/v1/scans)
›
(Header: x-scanner-key, Body: { scannedBarcodeValue })
STEP 8 REQUEST / ACTION Execute Mechanic
›
(Increment stamps/points)
STEP 9 REQUEST / ACTION Send Silent Push
›
(APNs Empty Payload)
STEP 10 REQUEST / ACTION Silent APNs Wakeup
STEP 11 RESPONSE Fetch Updated Pass (GET/v1/passes)
STEP 12 REQUEST / ACTION Deliver Fresh .pkpass
›
(Native Lock-Screen Alert
›
"Balance updated to %@")

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 Packager bundles pass.json, up to 13 image slots (image asset slot including @2x and @3x retina variants), and localized pass.strings into a .pkpass zip archive, computes manifest.json hashes, and signs the manifest via detached PKCS#7 encryption with your Apple Pass Type ID and Apple WWDR certificates. Multiple companion passes sharing a bundleId (Pass.bundleId) can be delivered together as a .pkpasses archive.
  • Google Wallet: The backend syncs class definitions (LoyaltyClass, EventTicketClass, GenericClass, etc.) with Google Wallet REST APIs and signs a RS256 JWT Save URL (https://pay.google.com/gp/v/save/:jwt).

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/:serialNumber with the header Authorization: ApplePass <authenticationToken>.
  • Passinstance validates the token and records the device's pushToken in the database, transitioning the pass status from AWAITING_OPT_IN to ACTIVE.

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/scans authenticated via x-scanner-key.
  • The Pass Mechanics Engine evaluates 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 .pkpass bundle.
  • Any field configured with a changeMessage containing the placeholder %@ generates a native iOS lock-screen notification.
  • Concurrently, Passinstance sends a REST PATCH request to the Google Wallet walletobjects endpoint, updating the Android card in real time.
Dashboard overview trends and KPIs
Dashboard overview trends and KPIs

Core API Endpoints & Verbs

Endpoint PathHTTP MethodAuthenticationFunctionality
/api/v1/templatesPOSTBearer / API KeyCreate a new pass template definition
/api/v1/templates/:id/publishPOSTBearer / API KeyPromote draft template to live production version
/api/v1/passesPOSTBearer / API KeyIssue a new pass with custom field values
/api/v1/passes/:idPATCHBearer / API KeyUpdate existing pass attributes and enqueue push
/api/v1/scansPOSTx-scanner-keyValidate pass barcode, apply mechanic, record scan
/v1/devices/...POSTApplePass <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 .pkpass from Passinstance servers.

Explore the complete 6-phase onboarding guide or review our API Architecture.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.