Skip to content
Help Center Guide · Pass Distribution
7 min readVerified 2026-11-16

Self-Service Distribution

Publish public PassFlow URLs, Embed Widgets/Buttons, Dynamic Wallet URLs, and NFC NDEF tags for walk-in customer enrollment.

In This Guide

Multi-Channel Pass Distribution Architecture

Passinstance provides seven distinct distribution modalities to deliver digital Apple Wallet (.pkpass) and Google Wallet passes to customers. Whether you are onboarding walk-in retail shoppers at a physical counter, embedding checkout buttons on an e-commerce website, triggering transactional emails from a CRM, or programming contactless smart stickers, Passinstance standardizes issuance through a unified pass generation engine:

1. Public PassFlow Form
Entry Point (UI / API)
Dashboard: PassFlowsURL: /f/:slugAPI: POST /api/v1/pass-flows/public/:url/generate
Primary Use Case
Retail counter QR stands, social links, event registration
End-User Friction
Low (fills mobile web form in browser)
Device & OS Support
Universal (iOS, Android, Desktop)
Verification & Gating
Optional Email/SMS OTP, reCAPTCHA, Cloudflare Turnstile, PaymentStep
2. Direct Smart Link
Entry Point (UI / API)
Dashboard: Pass Detail -> Smart LinkURL: /d/:slug, /s/:tokenAPI: GET /d/:slug/download
Primary Use Case
Personalized SMS/email links, member portal links
End-User Friction
Zero (1 tap to add to wallet)
Device & OS Support
Platform-aware (iOS Safari, Android Chrome, Desktop QR)
Verification & Gating
PIN protection (?pin=), single-device lock (limitToOneActivePerPass)
3. Delivery Center Sendouts
Entry Point (UI / API)
Dashboard: Delivery Center (/delivery-center)API: POST /api/v1/email-campaigns
Primary Use Case
Segmented bulk email/SMS, seasonal campaigns
End-User Friction
Low (clicks link in email/SMS)
Device & OS Support
Universal email clients & E.164 SMS
Verification & Gating
Suppression lists, RFC 8058 unsubscribe, managed email delivery/SNS or Custom SMTP
4. REST API Headless Issuance
Entry Point (UI / API)
API: POST /api/v1/passesPOST /api/v1/passes/upsert-by-external-id
Primary Use Case
CRM automation, POS backend, native mobile apps
End-User Friction
Invisible (minted behind the scenes)
Device & OS Support
Programmatic JSON response
Verification & Gating
API Key (passes scope), HMAC signatures, tenant isolation
5. High-Resolution QR Codes
Entry Point (UI / API)
Dashboard: Pass Detail -> Download QRAPI: GET /passes/:id/barcode, GET /d/:slug/qr
Primary Use Case
Table tents, receipts, product packaging, print flyers
End-User Friction
Low (point smartphone camera)
Device & OS Support
Native iOS & Android camera scanners
Verification & Gating
Scans redirect to Smart Link or PassFlow
6. NFC NDEF Smart Tags
Primary Use Case
Tap-to-enroll counter plaques, smart posters, VIP tables
End-User Friction
Zero (tap phone to tag, no camera app)
Device & OS Support
All NFC-enabled iPhones & Android devices
Verification & Gating
Standard NDEF URI record (read-only lock)
Entry Point (UI / API)
Physical NTAG213/215 stickers encoded with PassFlow or Smart Link URL
7. Embedded Wallet Badges
Entry Point (UI / API)
Dashboard: PassFlow -> EmbedHTML widget, iframe, or direct Add-to-Wallet buttons
Primary Use Case
E-commerce order confirmations, SaaS account portals
End-User Friction
1 click from desktop or mobile web
Device & OS Support
Browser-native with official Apple/Google badges
Verification & Gating
Session auth or signed temporary tokens
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
MULTI-CHANNEL PASS DISTRIBUTION MATRIX
STAGE 01 DISTRIBUTION MODALITY TOUCHPOINTS
[PassFlow Form] [Smart Link] [Sendouts] [REST API] [QR Barcodes] [NFC Tags] [Embedded Badges]
STAGE 02 PASSINSTANCE ENGINE & PIPELINE
Tenant Scoping & Quota Verification (billable_active_wallet_registrations)
Deduplication & Upsert Logic (upsert-by-external-id, email/phone match)
Optional Bot Protection (SpamProtectionMode), OTP Verification, Payment Checkout
Cryptographic Signing: Apple PassKit .pkpass (APNs token) & Google Wallet REST Class/Object
STAGE 03A APPLE WALLET (iOS / macOS)
MIME: application/vnd.apple.pkpass
Web Service Registration (/v1/devices/...)
Silent APNs Push Updates on Template Edits
STAGE 03B GOOGLE WALLET (Android / Web)
Signed JWT: pay.google.com/gp/v/save
Cloud Issuer Class & Object Mapping
Real-Time REST Patch Synchronization

1. Public PassFlow Self-Enrollment Forms

Public PassFlows (/f/:url, powered by PassFlow API at /api/v1/pass-flows/public/:url) allow customers to register for loyalty programs, event tickets, or membership cards without pre-existing accounts.

Workflow Stages:

  1. 1
    Intake (FormStep): Customer fills customizable fields (first name, last name, email, phone, custom properties). Built-in bot protection (SpamProtectionMode) evaluates submissions with Google reCAPTCHA v3 or Cloudflare Turnstile.
  2. 2
    Verification (EmailStep / OtpStep): When identity verification is enabled, Passinstance dispatches a 6-digit one-time passcode via POST /api/v1/pass-flows/public/:url/otp/send and validates it via POST .../otp/verify.
  3. 3
    Monetization (PaymentStep): For paid passes or ticket purchases, PassFlow embeds Stripe Elements, PayPal Orders, Paystack, or Mobile Money before pass creation.
  4. 4
    Handoff (PassStep): Once verified and paid, the pass is generated idempotently. The customer sees native Add to Apple Wallet and Save to Google Wallet buttons, alongside a QR code fallback.

Important: To prevent duplicate passes when an existing customer registers again, configure Deduplication Rules on the template. The system checks email, phone, or externalId and updates the existing active pass instead of minting a duplicate.


Every pass issued by Passinstance has a unique smart URL (passAccessUrl, /d/:slug, or /s/:token). When a customer clicks this link:

  • iOS Safari: Directly streams the signed .pkpass bundle, launching the native Apple Wallet "Add" modal sheet.
  • Android Chrome: Redirects to Google's cloud Add-to-Wallet URL (https://pay.google.com/gp/v/save/<jwt>).
  • Desktop Browsers: Displays a responsive PassFlow page with a scannable dynamic QR code, allowing the customer to scan the code with their smartphone camera or forward the link via email or SMS.

For complete details on language auto-detection and security cutoff windows, see the Download Links & PassFlow Guide.


3. Delivery Center Sendouts

Inside Delivery Center (/delivery-center), you can run targeted email or SMS distribution campaigns to deliver passes to customer segments:

  • Audience Filtering: Target specific templates, active passes, or uninstalled passes (onlyUninstalled: true).
  • High-Throughput Queue: Background background job queue workers process campaigns via managed EU email infrastructure (eu-central-1 Frankfurt) or your encrypted Custom SMTP server for email, and carrier SMS delivery for SMS.
  • Cost Transparency: Outbound delivery is billed transparently at €0.0005 per email and €0.03 per SMS (EUR), managed via Stripe top-up balances.

See the Email & SMS Delivery Guide for step-by-step authoring instructions.


4. Headless REST API Issuance

For programmatic integration with custom mobile apps, point-of-sale terminals, or backend CRMs, use the Passinstance REST API:

Endpoint: POST /api/v1/passes/upsert-by-external-id

Creates a new pass or updates an existing pass identified by externalId:

BASH
curl -X POST https://api.passinstance.com/api/v1/passes/upsert-by-external-id \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
    "externalId": "CUST-49102",
    "status": "ACTIVE",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "membershipTier": "Platinum",
      "points": 3400
    }
  }'

The response includes the unique passAccessUrl that you can render in your mobile app or send via your own transactional notifications.


5. High-Resolution QR Codes for Physical Collateral

You can generate QR codes for any pass or template to print on table tents, counter plaques, receipts, product packaging, or digital signage:

Exporting from Dashboard:

  1. 1
    Navigate to Templates or Passes in the dashboard.
  2. 2
    Open the pass detail card or template distribution panel.
  3. 3
    Click Download QR Code to export a clean vector SVG (for print designers) or high-resolution PNG (for web publishing).

API Generation:

Call GET /passes/:id/barcode via Barcode Resolution API to generate the barcode image dynamically, or embed GET /d/:slug/qr on custom landing pages. Supported symbologies include PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, and PKBarcodeFormatCode128.


6. NFC NDEF Smart Tags (Touchless Tap-to-Enroll)

Deploy touchless physical enrollment stations without purchasing specialized Apple VAS or Google Smart Tap merchant terminals:

  1. 1
    Obtain standard NTAG213, NTAG215, or NTAG216 NFC stickers or counter plaques.
  2. 2
    Open an NFC writing utility (such as NFC Tools on iOS or Android).
  3. 3
    Write an NDEF URI Record containing your public PassFlow link (e.g. https://app.passinstance.com/f/coffee-club-vip).
  4. 4
    Set the tag permissions to Lock Tag (Read-Only) to prevent tampering.
  5. 5
    Place the tag at your checkout counter. When customers tap their unlocked iPhone or Android smartphone against the tag, the enrollment form opens instantly without opening the camera app.

7. Embedded Wallet Badges & Widgets

Add official wallet badges to e-commerce checkout success pages, membership portals, or customer account settings:

HTML
<!-- Official Apple Wallet & Google Wallet Badges -->
<div class="wallet-buttons">
  <a href="https://app.passinstance.com/d/vip-club?pass=pass_01j8k9m2" target="_blank" rel="noopener">
    <img src="https://app.passinstance.com/assets/badges/add-to-apple-wallet.svg" alt="Add to Apple Wallet" height="40" />
  </a>
  <a href="https://app.passinstance.com/d/vip-club?pass=pass_01j8k9m2" target="_blank" rel="noopener">
    <img src="https://app.passinstance.com/assets/badges/save-to-google-wallet.svg" alt="Save to Google Wallet" height="40" />
  </a>
</div>

Sending Single Passes with Direct Email Delivery

When issuing a single pass manually from the Passinstance dashboard:

  1. 1
    Open the target template and click Create Pass (or use Quick Actions).
  2. 2
    Fill in customer attributes (name, email, membership number, balance).
  3. 3
    Check the "Send by Email" checkbox in the issuance modal.
  4. 4
    Click Create & Send. Passinstance generates the pass record and immediately calls POST /passes/:id/email/send in the background, dispatching a transactional email containing the personalized smart link ({passDownloadUrl}) directly to the recipient's inbox.

If custom SMTP is enabled on your workspace, this email routes through your own email server; otherwise, it sends via Passinstance's managed email delivery delivery infrastructure.


Do Template Changes Apply to Passes Across Distribution Channels?

When you modify a template and click Publish Changes:

  • Newly Issued Passes: All future passes created via PassFlow, REST API, or bulk CSV immediately inherit the latest design, images, colors, and field layouts.
  • Existing Installed Passes: Passinstance pushes updates automatically without requiring customers to re-download or scan anything:

- Apple Wallet: Sends silent APNs push notifications to registered Apple devices (Registration.pushToken). Devices wake up and fetch the updated .pkpass bundle. - Google Wallet: Updates the centralized Google Wallet Issuer Class (Google Wallet class sync), updating all active passes in real time.

  • Attribute Preservation: Updating template design or labels never overwrites personalized passholder data (such as loyalty points, customer names, or custom barcode values).
  • Voided & Expired Passes: Controlled by the template setting updateVoidedExpiredPasses. If disabled, revoked or expired passes are excluded from push updates to save network resources.

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.