Smart Download Link & PassFlow Architecture
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:
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
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
Browser
Accept-LanguageHeader: If no query parameter is supplied, the server parses the browser's HTTPAccept-Languageheader (e.g.fr-FR,fr;q=0.9,en-US;q=0.8) and matches the highest-priority language supported by your template. -
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
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 viaverifyDownloadPin. -
Query Parameter Bypass (
?pin=): In automated emails or SMS notifications, you can append?pin=1234to 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.pkpassbundle. -
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 toggleupdateVoidedExpiredPassesin Template Settings. When disabled, passes markedVOIDEDorEXPIREDdo 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:
Pass.status = 'ACTIVE'installedDevices = 0onlyUninstalled: true.Pass = null or Pass.archivedAt != nullGetting 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
Open the target pass in Passes -> Pass Details.
-
2
Click the Download QR Code button.
-
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:
GET /api/v1/passes/{passId}/barcode HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Supported query parameters:
-
format:png(default) orsvg. -
size: Output pixel dimensions (e.g.512for a 512x512 image). -
margin: Quiet zone margin size (default2).
On public download pages, GET /d/:slug/qr generates the QR code directly without authentication.
Troubleshooting: "Pass Link Says Card Invalid or Not Found"
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.
Smart Link API Reference
| Method | Endpoint Path | Auth Scope | Description |
|---|---|---|---|
| GET | /d/:slug | Public | Smart link entry router; redirects to /download/:slug or delivers JSON metadata. |
| GET | /d/:slug/info | Public | Returns public metadata (request payload), branding colors, and localized strings. |
| GET | /d/:slug/qr | Public | Renders on-the-fly QR code image for desktop display. |
| GET | /d/:slug/download | Public | Evaluates User-Agent and delivers .pkpass (iOS) or redirects to Google Save JWT (Android). |
| POST | /d/:slug/send-link-by-email | Public (Rate-Limited) | Sends download link to customer email address from desktop view. |
| POST | /d/:slug/send-link-by-sms | Public (Rate-Limited) | Dispatches download link to customer phone via E.164 SMS. |
| POST | /d/:slug/request-recovery | Public (Rate-Limited) | Generates a secure recovery email/SMS when a customer loses their pass. |
| GET | /passes/:id/barcode | API Key (passes) | Generates standalone barcode/QR code image in PNG or SVG format. |
Related Documentation
-
Self-Service Distribution — Overview of all 7 pass distribution channels.
-
Email & SMS Delivery — Outbound campaigns, email templates, and delivery gates.
-
Find or Recover Your Pass — Customer self-service recovery workflows.
