Core Platform Architecture & Entities
To build reliable wallet workflows, developers and administrators must understand how Passinstance organizes templates, dynamic pass records, business logic mechanics, and device registration states.
Backend Entity Schema & platform resource Mapping
Each platform concept directly corresponds to a structured platform resource within the Passinstance API database layer:
| Concept | platform resource | Responsibilities & Stored Attributes | |||||
|---|---|---|---|---|---|---|---|
| Template | Template | Stores visual configuration, layout kind (pass type), asset relations (image asset slot), barcode rules, custom identifier regexes, and single-table versioning (groupId, versionNumber, rowKind: `PRODUCTION \ | PUBLISHED \ | ARCHIVED \ | DRAFT, status`: template status). | ||
| Pass | Pass | Represents an individual issued card. Holds id, unique serialNumber, authenticationToken, downloadCode, optional tenant-unique externalId, optional bundleId (bundleId), optional idempotencyKey, structured JSON attributes, expirationDate, artifact readiness (appleArtifactStatus, googleArtifactStatus), and lifecycle/void flags. | |||||
| Pass Mechanic | pass mechanic | Configures stateful rules attached to a template. Stores mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, tiers (PassTier), and cap handling rules. | |||||
| Prepaid Account | prepaid account | Manages stored monetary value for gift and prepaid cards. Tracks integer balance units and links to immutable prepaid ledger entry transaction logs. | |||||
| Pass Bundle | pass bundle | Groups up to 10 companion passes via Pass.bundleId (bundle grouping mode: `AUTO \ | MANUAL, BundleStatus: ACTIVE \ | CANCELLED) to download multi-card .pkpasses` archives. | |||
| Wallet Experience | PassProject | Orchestrates a primary template (mainTemplateId) and linked templates (PassProjectTemplateRole: `PRIMARY \ | LINKED \ | PRIVACY_MODE \ | INACTIVE \ | VIP \ | CUSTOM`), unified claim pages, bundles, segments, and visual automation flows. |
| PassFlow | PassFlow | Manages multi-step self-service intake pages (/f/:url, PassFlowType, PassFlowStatus) with customizable forms, SMS/Email OTP verification, bot protection (SpamProtectionMode), payment gateways, and direct wallet handoffs. | |||||
| Scanner Configuration | ScannerConfiguration | Configures physical check-in locations (ValidationPlace), scoped ScannerKey tokens, validation modes (ScanMode), NFC reader settings (NfcReaderMode), and offline dataset sync. |
Core Pass Identifiers & Correlation Keys
When integrating CRMs, e-commerce checkouts, or ticketing backends, understand the exact role of each identifier on a Pass:
| Field | Passinstance database Column / Scope | Mutability & Format | Primary Purpose |
|---|---|---|---|
id | UUID primary key | System-generated, immutable | Internal API resource reference (GET /api/v1/passes/:id). |
serialNumber | Globally unique string | System-generated (or custom when configured), immutable | Canonical Apple Wallet .pkpass identifier and Google object suffix. |
externalId | @unique([customerId, externalId]) where archivedAt IS NULL | Caller-supplied string (max 255 chars) | Business key from your CRM, POS, or ticketing DB enabling idempotent POST /api/v1/passes/upsert-by-external-id and lookup via GET /api/v1/passes/by-external-id/:externalId. |
bundleId | bundleId (UUID foreign key to pass bundle) | System-managed via /api/v1/bundles/* or PassProject | Groups up to 10 passes into a multi-card .pkpasses Apple bundle or unified claim experience. |
idempotencyKey | @unique([customerId, idempotencyKey]) | Supplied via Idempotency-Key header (<=128 chars [A-Za-z0-9._:-]+) | Prevents duplicate pass issuance if an HTTP POST /api/v1/passes request is retried; verified via SHA-256 request body hash. |
downloadCode / authenticationToken | Per-pass security tokens | System-generated cryptographic strings | Public short download code and Apple Web Service Authorization: ApplePass <token> shared secret. |
State Machine Enums & Lifecycle Mapping
Pass records transition through strict state machines across Passinstance database enums during creation, wallet sync, and voiding/deletion:
Pass Status (pass status)
-
DRAFT: Provisioned as an unissued draft and not yet available for public installation. -
AWAITING_OPT_IN: Generated during opt-in/OTP registration flows; awaiting verification before activation. -
GENERATING: Undergoing asynchronous pass or artifact generation. -
ACTIVE: Issued and valid. Available for wallet installation and scanner validation. -
INACTIVE: Temporarily paused/deactivated; scanners reject validation until reactivated. -
EXPIRED: Passed itsexpirationDate; scanners reject with reasonPASS_EXPIRED. -
REDEEMED: Single-use coupon or voucher that has completed redemption. -
CANCELLED,SUSPENDED,PENDING_ACTIVATION: Specialized billing, administrative, and pre-activation states. -
VOIDED: Revoked or voided by an administrator or scan rule; scanners reject withPASS_VOIDED.
Pass Lifecycle, Deletion Mode & Artifact Readiness
-
PassLifecycleStatus: Controls irreversible voiding and purge transitions:
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: Distinguishes soft deletion (SOFT, preserves audit history and freesexternalIduniqueness for live passes) vs. permanent removal (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatus&googleArtifactStatus): Tracks per-ecosystem generation health (NOT_GENERATED,GENERATING,READY,FAILED,INVALIDATED).
Wallet Void & Propagation Status (walletVoidStatus / WalletPropagationStatus)
Tracks asynchronous propagation of void/update state to Apple APNs and Google Wallet on the Pass.walletVoidStatus field:
-
NONE: No propagation pending. -
PENDING: State recorded in database; awaiting queue enqueue. -
QUEUED: Dispatched to background job queue wallet sync workers. -
SUCCEEDED: Apple APNs wake-up or Google RESTPATCHacknowledged. -
FAILED: Downstream wallet push failed (eligible for automated retry or manual regeneration).
Custom Properties & Dynamic Token Interpolation
Passinstance uses dynamic bracket syntax {propertyName} to bind customer data into card fields:
-
Syntax: Place
{firstName},{pointsBalance}, or{membershipTier}in any primary, secondary, auxiliary, or back field label or value. -
Change Messages: Configure
changeMessage: "You earned a stamp! You now have %@ stamps."on Apple Wallet fields. When updated, the%@token is replaced with the new value, generating an immediate iOS lock-screen notification banner. -
Attributed Values: Apple Wallet back fields support HTML anchor tags (
<a href="https://example.com">Terms</a>) for clickable web links, phone numbers, and email addresses.
Important: Billing capacity meters Active Wallet Passes (the total number of devices currently registered via Apple APNs or Google Wallet objects), rather than unissued draft records or expired passes.
