Skip to content
Help Center Guide · Quick StartOnboarding Phase 2
3 min readVerified 2026-11-16

Create Your First Wallet Pass

Design a template, assign a pass mechanic, bind dynamic attributes, publish safely, and install a test pass on your phone.

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 focus1 / 2
Key UI elements

Templates directory & adoption bar (Zoomed)

Filter templates, monitor Installed vs. Removed wallet counts per template, and open previews, the Visual Editor, or single-pass creation.

Overview

Creating your first wallet pass involves configuring a reusable visual Template, binding interactive business mechanics, performing a pre-publish risk check, and issuing a concrete Pass record that can be installed on iOS and Android devices.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
FIRST PASS CREATION & INSTALLATION
STAGE 01
1
TEMPLATE AUTHORING (POST/api/v1/templates)
Select pass type (storeCard, coupon, eventTicket, membership)
Configure Colors (rgb(r,g,b) for Apple, #RRGGBB for Google) & Assets
Attach pass mechanic (STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD)
STAGE 02
2
PRE-PUBLISH RISK CHECK & PROMOTION (POST/api/v1/templates/:id/publish)
Evaluate GET/api/v1/templates/:id/publish-risk-check
Promote revision from rowKind = DRAFT to rowKind = PRODUCTION
STAGE 03
3
PASS ISSUANCE & WALLET INSTALLATION (POST/api/v1/passes)
Optional Idempotency-Key header (idempotencyKey) & externalId
Hydrate structured JSON attributes (memberName, points, barcodeValue)
Deliver Smart URL (/p/:passId / /d/:slug)Install on iOS / Android

Step-by-Step Creation Milestones

Follow this workflow in Passinstance Dashboard (Templates -> Create Template at /templates/new) or via the Developer API:

  1. 1
    Select Layout Geometry (pass type): Choose one of the supported pass formats:

- storeCard: Loyalty cards, stamp cards, and gift cards. - coupon: Single-use promotional vouchers and discount tickets. - eventTicket / boardingPass: Concerts, sports, festivals, conferences, or airline/rail boarding passes. - membership / generic / posterGeneric / studentId / businessCard: Club cards, WWDC poster cards, employee/student IDs, and digital business cards.

  1. 2
    Branding, Colors & Assets:

- Color Formatting: Apple Wallet strictly enforces rgb(r, g, b) strings (without alpha channels). Google Wallet accepts hex #RRGGBB. The dashboard color picker automatically converts and warns on low WCAG contrast. - Asset Slots (image asset slot): Upload high-resolution images across the 13 supported slots (logo, primaryLogo, secondaryLogo, icon, googlePayLogo, strip, background, thumbnail, artwork, venueMap, footer, androidBackground, androidLogo).

  1. 3
    Attach an Interactive Pass Mechanic:

- Choose a rule engine (mechanic type): STAMP_CARD_ADD, STAMP_CARD_DEDUCT, LOYALTY_PROGRAM, PREPAID_CARD, VALID_ONCE_PER_DAY, or RENEW_EXPIRATION.

  1. 4
    Define Dynamic Field Zones (field placement type):

- Place fields into HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, or FOOTER. - Use dynamic curly tokens like {memberName}, {pointsBalance}, or {expirationDate}. - Add Apple changeMessage strings containing %@ (for example, "Points updated: %@") to trigger native iOS lock-screen push notifications.

  1. 5
    Pre-Publish Risk Analysis & Publishing:

- The dashboard evaluates GET /api/v1/templates/:id/publish-risk-check to detect critical changes that could overwrite live pass fields. - Click Save & Publish (POST /api/v1/templates/:id/publish) to promote the DRAFT revision into the PRODUCTION base row.

  1. 6
    Generate & Install a Test Pass:

- Click Create Pass on the template overview (/templates/:id/overview) or dispatch a REST request to POST /api/v1/passes. Pass creation automatically calls resolvePassCreationTemplateId to bind the new pass to the canonical base template row.

Template list and quick creation actions
Template list and quick creation actions

Programmatic Pass Generation & Verification

Developers can bypass the dashboard and issue personalized wallet passes directly from backend systems or CRMs using POST /api/v1/passes (request payload). Include Idempotency-Key for safe retries and externalId for CRM correlation, and optionally pass ?includePassSource=apple|google to receive direct wallet source artifacts inline:

HTTP Request

POST /api/v1/passes?includePassSource=google
Headers
X-API-Key <API_KEY>
Content-Type application/json
Idempotency-Key order-94021-pass-init
JSON
{
  "templateId": "tmpl_9a8b7c6d5e4f",
  "externalId": "cust_100248",
  "attributes": {
    "memberName": "Elena Rostova",
    "memberNumber": "MB-94021",
    "points": "150"
  },
  "barcodeValue": "PI-MB-94021-SECURE",
  "barcodeAltText": "MB-94021",
  "expirationDate": "2027-12-31 23:59"
}

HTTP Response (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_1a2b3c4d5e6f",
    "templateId": "tmpl_9a8b7c6d5e4f",
    "serialNumber": "PI-789042-XY",
    "externalId": "cust_100248",
    "bundleId": null,
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/d/elena-rostova-94021",
    "passAccessUrl": "https://app.passinstance.com/p/pass_1a2b3c4d5e6f",
    "passSource": {
      "platform": "google",
      "saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "createdAt": "2026-11-15T12:00:00Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Sandbox Sample Pass Testing

During evaluation and initial testing, you can generate an instant sample pass without entering complete customer records:

  1. 1
    Call POST /api/v1/onboarding/sample-pass or click Try Sample Pass in the /onboarding/try-pass wizard step.
  2. 2
    The server creates an ephemeral pass and exposes the public sample endpoint:
GET /api/v1/onboarding/sample-pass/public/:sessionId
  1. 3
    Scan the displayed QR code with an iPhone camera to trigger native Apple Wallet installation, or open the link on Android to test Google Wallet.
  2. 4
    Open the Scanner (/scanner) in Passinstance Dashboard or pair the Passinstance Scanner mobile app via POST /api/v1/scanner-keys/from-link and scan the installed pass to test live scan events and instant push notifications.

Important: Always test your newly published pass on both iOS (Apple Wallet) and Android (Google Wallet) devices to verify color contrast, field text truncation, and barcode scan reliability before launching customer-facing distribution campaigns.

Ready to start? Launch Phase 2: Design Your Pass or explore Create Wallet Passes with AI.

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.