Resolving Common Pass Installation & Scanning Issues
Most passholder installation or checkout scanning hiccups are caused by embedded social-app browsers, Google Account mismatches, download security gates (verifyDownloadPin / downloadUntil), or screen glare at the checkout counter.
Diagnostic Reference for Passholder Download Gates
When troubleshooting why a smart link (/d/:slug, /download/:slug, or /s/:token) does not immediately open Apple Wallet or Google Wallet, check the response status and security gate behavior:
| Symptom / Gate Behavior | Backend Mechanism | Cause & Passholder Fix |
|---|---|---|
| "Safari cannot download this file" or blank screen on iPhone | Embedded WKWebView MIME restriction | Link was opened inside Instagram, TikTok, Facebook, LinkedIn, or an email previewer. Tap ... -> Open in System Browser (Safari) so iOS can install the bundleId-signed .pkpass. |
| Pass requires a 4- to 6-digit PIN | verifyDownloadPin (Public Download Page) | The issuer enabled download PIN protection (pinVerified: false until satisfied). Enter the PIN on the PassFlow page (GET /d/:slug?pin=...) or email/SMS prompt to unlock the wallet links. |
Link Expired (downloadUntil) | downloadUntil timestamp enforcement | The time-limited download token has expired. Use the on-page recovery button (POST /d/:slug/request-recovery with { emailOrPhone }) to receive a fresh link. |
Device Limit Reached (HTTP 403 Forbidden) | limitToOneActivePerPass: true | The pass is already active on another device. Remove the pass from your old phone first or ask the issuer to reset device binding. |
| Card saved on Android, but missing in Google Wallet app | Google Account profile mismatch | Chrome was signed into a secondary Gmail account while the Google Wallet app is viewing your primary account. Switch accounts via the top-right avatar in Google Wallet. |
Unlocking a PIN-Protected Download Page
When a template, Wallet Experience pack, or Download Page requires PIN verification before streaming the signed .pkpass or Google Save URL, Public Download Page validates the PIN via verifyDownloadPin (accepting either the header or ?pin= query parameter on /d/:slug and /d/:slug/download) and withholds wallet download URLs (error=pin_required / pinVerified: false) until the valid PIN is entered on the PassFlow UI.
Fixing Optical Barcode & NFC Scanning Issues at Checkout
If a retail POS scanner or venue smartphone camera struggles to read your pass at the counter:
-
1
Maximize Screen Brightness: Apple Wallet and Google Wallet automatically boost screen backlight when a barcode is displayed, but aggressive battery-saver modes can override this. Slide your phone's brightness up manually.
-
2
Disable Dark-Tint Privacy Screen Protectors: Polarized privacy glass filters dramatically reduce contrast at off-axis angles under overhead store lighting. Hold the phone flat and directly facing the optical scanner window (
10–15 cmdistance). -
3
Hold Near the NFC Contactless Symbol: For passes configured with Apple VAS or Google Smart Tap (
NFC), hold the top edge of your iPhone or the center-back of your Android phone directly against the reader's contactless wave icon for 1 second and complete Face ID / Touch ID / biometric unlock if prompted. -
4
Use the Human-Readable Serial Number: Every barcode pass includes a fallback code (
serialNumberor member ID) printed directly beneath the QR/PDF417/Code128 graphic so staff can look up the pass viaGET /api/v1/scans/pass?barcode=...if your screen is cracked.
Important: If you see an expired or voided badge across your pass (pass status:
VOIDEDorEXPIRED), the card has already been redeemed or reached its validity end date and will be rejected by the venue scanner (ALREADY_VOIDED/PASS_VOIDED_AFTER_SCANorEXPIRED).
Still need assistance? See Add a Pass to Your Wallet or reach out via Contact Support.
