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:
/f/:slugAPI: POST /api/v1/pass-flows/public/:url/generate/d/:slug, /s/:tokenAPI: GET /d/:slug/download?pin=), single-device lock (limitToOneActivePerPass)/delivery-center)API: POST /api/v1/email-campaignsPOST /api/v1/passesPOST /api/v1/passes/upsert-by-external-idpasses scope), HMAC signatures, tenant isolationGET /passes/:id/barcode, GET /d/:slug/qr1. 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
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
Verification (
EmailStep/OtpStep): When identity verification is enabled, Passinstance dispatches a 6-digit one-time passcode viaPOST /api/v1/pass-flows/public/:url/otp/sendand validates it viaPOST .../otp/verify. -
3
Monetization (
PaymentStep): For paid passes or ticket purchases, PassFlow embeds Stripe Elements, PayPal Orders, Paystack, or Mobile Money before pass creation. -
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
phone, orexternalIdand updates the existing active pass instead of minting a duplicate.
2. Direct Smart Download Links
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
.pkpassbundle, 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-1Frankfurt) 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:
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
Navigate to Templates or Passes in the dashboard.
-
2
Open the pass detail card or template distribution panel.
-
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
Obtain standard NTAG213, NTAG215, or NTAG216 NFC stickers or counter plaques.
-
2
Open an NFC writing utility (such as NFC Tools on iOS or Android).
-
3
Write an NDEF URI Record containing your public PassFlow link (e.g.
https://app.passinstance.com/f/coffee-club-vip). -
4
Set the tag permissions to Lock Tag (Read-Only) to prevent tampering.
-
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:
<!-- 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
Open the target template and click Create Pass (or use Quick Actions).
-
2
Fill in customer attributes (name, email, membership number, balance).
-
3
Check the "Send by Email" checkbox in the issuance modal.
-
4
Click Create & Send. Passinstance generates the pass record and immediately calls
POST /passes/:id/email/sendin 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 Documentation
-
Download Links & PassFlow — Smart link routing, PIN protection, and PassFlow localization.
-
Email & SMS Delivery — Delivery Center campaigns, email templates, and delivery runtime gates.
-
Selling Passes — Monetizing digital passes via PassFlow checkout.
-
UTM Tracking Parameters — Attribution telemetry and channel conversion tracking.
