Overview
Setting up a Passinstance account initializes your isolated tenant workspace, configures your regional preferences, and guides you through an automated onboarding pipeline to generate ready-to-test demo passes for Apple Wallet and Google Wallet.
Onboarding Pipeline & State Machine
Passinstance manages account initialization via an automated OnboardingSession state machine backed by the Onboarding API:
Onboarding Steps & Enums
The session transitions through the exact OnboardingStep enum values:
-
1
WALLET_SETUP: Review and accept platform wallet issuance terms (googleWalletAccepted) and prepare default demo credentials. -
2
PERSONALIZE: Select your business model and anticipated monthly volume tier:
- EVALUATING: Testing capabilities and sandbox exploration. - UP_TO_500: Boutique stores, local clubs, specialized venues. - RANGE_500_5000: Growing retailers, regional gyms, medium events. - RANGE_5000_25000: Multi-location franchises and large membership associations. - RANGE_25000_PLUS / ENTERPRISE: High-volume ticketing, national retail loyalty, airline/transit passes.
-
3
GENERATING_DEMOS: The backend enqueues background jobs that provision demo templates acrossOnboardingUseCasecategories (LOYALTY_AND_CUSTOMER_CARDS,MEMBERSHIP_CARDS,TICKETING,VOUCHERS_OR_COUPONS,GIFT_CARDS_OR_PREPAID_CARDS,BUSINESS_CARDS,EMPLOYEE_IDS,INSURANCE_WARRANTY_AND_SERVICE_CARDS,OTHER). -
4
TRY_PASS: Generates an ephemeral sample pass with a scannable QR code for instant phone installation. -
5
DONE: Onboarding concludes and unlocks the full administrative dashboard (/dashboard).
Onboarding Controller API Reference
Developers and automated provisioning scripts can drive onboarding programmatically under /api/v1/onboarding:
| Endpoint Path | Method | Auth | Payload / Parameters | Description |
|---|---|---|---|---|
/api/v1/onboarding | GET | Bearer | None | Retrieves current onboarding session state, active step, and generated demos. |
/api/v1/onboarding/wallet-setup | PUT | Bearer | { "googleWalletAccepted": true } | Accepts wallet issuance terms and provisions default Google Wallet setup. |
/api/v1/onboarding/personalize | PUT | Bearer | { expectedPassVolume, useCases: [] } | Stores business volume tier and selected OnboardingUseCase items. |
/api/v1/onboarding/demos | POST | Bearer | None | Triggers async generation of demo templates (QUEUED -> READY). |
/api/v1/onboarding/demos | GET | Bearer | None | Polls demo generation progress across requested use cases. |
/api/v1/onboarding/demos/:type/retry | POST | Bearer | URL param :type | Retries demo template generation if a specific catalog type failed. |
/api/v1/onboarding/sample-pass | POST | Bearer | { templateId? } | Generates a live test pass for immediate wallet installation. |
/api/v1/onboarding/sample-pass/public/:sessionId | GET | None | URL param :sessionId | Unauthenticated public endpoint to view/install the sample pass on mobile. |
/api/v1/onboarding/complete | POST | Bearer | { skipSamplePass?: boolean } | Marks the onboarding session as DONE. |
Account Setup Checklist
Follow these milestones in Passinstance Dashboard to prepare your workspace for production launch:
-
1
Verify Workspace & Email: Confirm your email address (any valid email works) upon registration to establish your administrative tenant credentials, pre-provisioned with a Demo Apple Certificate and Managed Google Wallet Issuer.
-
2
Configure Regional Settings: Visit Settings -> General (
/settings/workspace/general) or callPUT /api/v1/customer/:customerId/regional-settingsto configure:
- Timezone: Evaluates daily scan caps and local timestamps (e.g. Europe/Berlin, America/New_York). - Currency: Sets default ISO 4217 currency for prepaid balances (e.g. EUR, USD, GBP). - Default Language: Sets primary language for localized wallet fields.
-
3
Configure Apple Wallet Certificate (Production): In Settings -> Wallet -> Apple Certificates (
/settings/workspace/wallet), generate a Certificate Signing Request viaPOST /api/v1/certificates/generate-csr, upload it to the Apple Developer Portal under Pass Type IDs, and import the signed.cerfile viaPOST /api/v1/certificates. -
4
Configure Google Wallet Issuer (Production): Under Settings -> Wallet -> Google Wallet, run setup (
POST /api/v1/google-wallet/setup) and check status (GET /api/v1/google-wallet/status) to inspect your Google Issuer ID and Smart TapcollectorId. -
5
Team Roles & Access Control: Under Settings -> Access -> Members & Roles (
/settings/workspace/access), invite staff using organization roles (OrganizationMemberRole:OWNER,ADMIN,MEMBER) alongside workspace RBAC roles (DEFAULT_ROLES:super-admin,admin,editor,user,customer) and enforce Two-Factor Authentication (enforceTwoFactorAuth).
Prerequisites: To issue custom-branded production passes in Apple Wallet, you must have an active Apple Developer Program membership ($99/year) to generate an Apple Pass Type ID certificate (
pass.com.yourcompany.app). Testing during the onboarding sandbox uses Passinstance demo certificates.
Review our available Plans & Capacity Tiers or proceed directly to Phase 2: Design Your Pass.
