Skip to content
Help Center Guide · Pass DistributionOnboarding Phase 5
8 min readVerified 2026-11-16

Download Links & PassFlow

Customize smart OS-detecting PassFlow download pages, PassTour overlays, PIN locks, re-download limits, and Pause Downloads safeguards.

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

Issuance limits & Access controls (Zoomed)

Configure Unlimited or Limited issuance, Access channels, Wallet support & routing, and safeguards like 'Block re-download after activation' and 'Deduplicate campaign recipients'.

Every digital pass issued in Passinstance is distributed through a single canonical smart link (passAccessUrl, /d/:slug, or /s/:token). When a customer opens this link, the Smart Download Engine (Public Download Page at /d/:slug and /download/:slug) inspects the incoming client's HTTP headers, operating system, browser context, security state, and preferred language before delivering the appropriate platform wallet payload:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SMART DOWNLOAD RESOLUTION & ERROR GATES
STAGE 01 INCOMING CLIENT HTTP GET REQUEST
GET/d/:slug | GET/download/:slug | GET/s/:token Headers: User-Agent, Accept-Language, X-Wallet-Experience-Pin
STAGE 02 ACCESS GUARD & INTEGRITY VALIDATION GATES
1
Pass & Template Verification: Pass exists, not soft-deleted (archivedAt: null)
2
Status Check: Pass is not voided (voided: false) & not expired
3
Time Window Check: now() <= template.enableDownloadUntil
4
PIN Challenge Gate: verifyDownloadPin(pin) (throws 403 on mismatch)
5
Device Lock: If limitToOneActivePerPass, verify device registrations == 0
STAGE 03 LOCALIZATION & LANGUAGE RESOLUTION PIPELINE
Query ?lang=Header Accept-Languagetemplate.defaultLanguageen
iOS Safari / WebKit
STAGE 04A Stream .pkpass ZIP
Content-Type: application/vnd.apple. pkpass
Android Chrome
STAGE 04B 302 Redirect to
Signed Google JWT pay.google.com/ gp/v/save/<jwt>
Desktop / In-App WebView
STAGE 04C Render Branded PassFlow
Page in Resolved Locale
+ High-Res QR Code
+ Language Selector

PassFlow Localization & Language Detection

Passinstance automatically localizes the PassFlow download page, button labels, pass attribute values, and instructional guides based on the customer's browser preferences.

Language Resolution Hierarchy

When a recipient opens a pass link, Passinstance resolves the locale using a strict 4-tier fallback hierarchy:

  1. 1
    Explicit Query Parameter (?lang=): If the URL contains ?lang=de, ?lang=es, ?lang=fr, or another supported ISO-639-1 language code, this language takes immediate precedence.
  2. 2
    Browser Accept-Language Header: If no query parameter is supplied, the server parses the browser's HTTP Accept-Language header (e.g. fr-FR,fr;q=0.9,en-US;q=0.8) and matches the highest-priority language supported by your template.
  3. 3
    Template Default Language (template.defaultLanguage): If the browser language is not available in your template localization dictionary, Passinstance falls back to the default language defined in your Template Settings.
  4. 4
    Platform Global Fallback (en): If no matching localization is found, English is served by default.

Public Language Selector Dropdown

The public PassFlow page includes a language selector dropdown in the top-right corner. When visitors select a different language, the page updates dynamically (appending ?lang=<locale> without reloading the session) and immediately renders translated pass field labels, descriptions, and PassTour onboarding steps.


PIN Protection & Download Access Guards

To prevent unauthorized pass claiming, sensitive membership cards or ticket bundles can be gated behind a security PIN:

  • Enabling PIN Protection: Set a numeric or alphanumeric PIN on your template or Pass Project.
  • Verification Gate (verifyDownloadPin): When a pass requires a PIN, visiting the link directly prompts the customer with a secure entry challenge. The server validates the PIN via verifyDownloadPin.
  • Query Parameter Bypass (?pin=): In automated emails or SMS notifications, you can append ?pin=1234 to the download link so legitimate recipients bypass the manual prompt automatically.
  • Brute-Force Rate Limiting: The PIN endpoint is rate-limited to 5 failed attempts per IP address per minute to block credential attacks.

Do Template Changes Apply to Passes?

When you edit a template in Passinstance and click Publish Changes, the system propagates updates across your entire pass population:

1. Newly Downloaded Passes

Anyone who downloads a pass after publication immediately receives the updated .pkpass archive or Google Wallet object with all latest design changes, strip images, logos, colors, and layout configurations.

2. Existing Installed Passes

  • Apple Wallet: Passinstance dispatches silent APNs (Apple Push Notification service) push notifications to all registered Apple devices (Registration.pushToken). Devices wake up in the background, query Passinstance's Apple Wallet Web Service (GET /v1/devices/{deviceLibraryIdentifier}/registrations/...), and fetch the updated .pkpass bundle.
  • Google Wallet: Passinstance updates the centralized Google Wallet Issuer Class (Google Wallet class sync). Because Google Wallet passes reference the Issuer Class in the cloud, all Android devices reflect visual changes (banner images, logo, colors, issuer name) immediately without reissuing.
  • Dynamic Field & Attribute Protection: Personal data bound to individual passholders (e.g. {firstName}, {points}, {externalId}, or custom barcodes) is never overwritten by template design changes.
  • Excluding Revoked Passes (updateVoidedExpiredPasses): You can toggle updateVoidedExpiredPasses in Template Settings. When disabled, passes marked VOIDED or EXPIRED do not receive APNs push pings, reducing unnecessary server and push traffic.

"Not Installed" vs. "Not Found": Understanding Pass States

In support inquiries and audit logs, merchants often confuse "Not Installed" with "Not Found". These two states represent completely different points in the pass lifecycle:

Not Installed (Unclaimed)
200 OK
Status in Database
Pass.status = 'ACTIVE'installedDevices = 0
What It Means
The pass record exists and is valid, but the recipient has not yet tapped Add to Apple Wallet or Save to Google Wallet on a mobile device.
How to Resolve
Send an email/SMS reminder via Delivery Center targeting passes with onlyUninstalled: true.
Not Found (Lookup Failure)
404 Not Found
Status in Database
Pass = null or Pass.archivedAt != null
What It Means
The server cannot find a valid pass record matching the URL slug, token, or ID. The link is broken, expired, revoked, or belongs to a different workspace.
How to Resolve
Check the token in the URL, verify the pass was not deleted in the dashboard, or reissue the pass.

Getting the QR Code of a Pass as an Image

You can download high-resolution QR code images for any pass or template for use in printed marketing collateral, physical receipts, or digital signage:

Exporting from Dashboard

  1. 1
    Open the target pass in Passes -> Pass Details.
  2. 2
    Click the Download QR Code button.
  3. 3
    Choose your format:

- Vector SVG: Best for graphic designers and large physical print materials (billboards, banners, counter stands). - High-Res PNG: Best for web pages, email signatures, and receipts.

Programmatic QR Code API

You can fetch the QR code dynamically using the Passinstance API:

HTTP
GET /api/v1/passes/{passId}/barcode HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>

Supported query parameters:

  • format: png (default) or svg.
  • size: Output pixel dimensions (e.g. 512 for a 512x512 image).
  • margin: Quiet zone margin size (default 2).

On public download pages, GET /d/:slug/qr generates the QR code directly without authentication.


If a recipient clicks their pass link and encounters an error stating "Card Invalid or Not Found", check the following eight root causes:

1. Pass Was Voided (pass.voided === true)

If a staff member or automated webhook voided the pass (e.g. after a refund, membership cancellation, or voucher redemption), the download link rejects further wallet additions. Fix: In the dashboard, locate the pass, inspect the Audit Log, and click Unvoid Pass if the deactivation was accidental.

2. Pass Has Expired (pass.expirationDate < now())

If the pass has a fixed expiration date or dynamic duration (validityInDays) that has elapsed, the download page displays an expiration notice. Fix: Extend the expirationDate on the pass record in the dashboard or via PATCH /api/v1/passes/:id.

3. Outside Download Window (enableDownloadUntil)

Templates can enforce a download cutoff timestamp (enableDownloadUntil). If a customer clicks the link after this date, new downloads are blocked even if existing installed passes remain active. Fix: In Template Settings -> Distribution & Access, extend or clear the Enable Download Until cutoff date.

4. Template Is in Draft or Archived (template.status !== 'PUBLISHED')

Passes cannot be downloaded if the parent template is archived or in draft state. Fix: Navigate to the template and ensure its status is set to Published.

5. Pass Was Soft-Deleted (pass.archivedAt !== null)

If the pass record was deleted from the dashboard or through bulk deletion, its unique download token is invalidated immediately. Fix: Check Trash / Archived Passes in the dashboard to restore the pass, or issue a new pass.

6. Incorrect or Missing Download PIN

If PIN protection is enabled, entering the wrong PIN triggers a 403 Forbidden error. Fix: Confirm the customer has the correct PIN, or generate a pre-authenticated link containing ?pin=<correct_pin>.

7. Single-Device Lock (limitToOneActivePerPass: true)

When Single-Device Binding is active, the link locks permanently once the first device installs the pass. If the recipient tries to download it on a second device or forwarded the link to a friend, subsequent downloads are rejected. Fix: If the customer replaced their phone, use Request Recovery on the download page or click Reset Device Binding in the dashboard pass detail view.

8. Missing Apple Signing Certificate

If your workspace Apple Pass Type Certificate (.p12) expired or was unlinked, Apple Wallet .pkpass generation fails with a signing error. Fix: Navigate to Settings -> Certificates and verify that your Apple Pass Type Certificate is valid and active.


MethodEndpoint PathAuth ScopeDescription
GET/d/:slugPublicSmart link entry router; redirects to /download/:slug or delivers JSON metadata.
GET/d/:slug/infoPublicReturns public metadata (request payload), branding colors, and localized strings.
GET/d/:slug/qrPublicRenders on-the-fly QR code image for desktop display.
GET/d/:slug/downloadPublicEvaluates User-Agent and delivers .pkpass (iOS) or redirects to Google Save JWT (Android).
POST/d/:slug/send-link-by-emailPublic (Rate-Limited)Sends download link to customer email address from desktop view.
POST/d/:slug/send-link-by-smsPublic (Rate-Limited)Dispatches download link to customer phone via E.164 SMS.
POST/d/:slug/request-recoveryPublic (Rate-Limited)Generates a secure recovery email/SMS when a customer loses their pass.
GET/passes/:id/barcodeAPI Key (passes)Generates standalone barcode/QR code image in PNG or SVG format.

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.