Skip to content
Help Center Guide · Help for Passholders
3 min readVerified 2026-11-16

Resolve Wallet Issues

Fix iOS Safari vs. in-app browser .pkpass blocking, Android Google Wallet account mismatches, and scanner glare issues.

In This Guide

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.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
DOWNLOAD GATE & BROWSER HANDOFF DIAGNOSTICS
STAGE 01 PASSHOLDER OPENS /d/:slug, /download/:slug, OR /s/:token
STAGE 02A WEBVIEW INTERCEPTION
Instagram/TikTok iOS blocks .pkpass
Prompt user to tap
"Open in Safari"
STAGE 02B EXPIRED LINK HANDOFF
Link past downloadUntil
Prompts user to request fresh link viaPOST/d/:slug/request- recovery
STAGE 02C PIN VERIFICATION GATE
-Prompts user on /d/:slug and checks verifyDownloadPin with ?pin= / header before streaming pass

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 BehaviorBackend MechanismCause & Passholder Fix
"Safari cannot download this file" or blank screen on iPhoneEmbedded WKWebView MIME restrictionLink 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 PINverifyDownloadPin (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 enforcementThe 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: trueThe 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 appGoogle Account profile mismatchChrome 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. 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. 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 cm distance).
  3. 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. 4
    Use the Human-Readable Serial Number: Every barcode pass includes a fallback code (serialNumber or member ID) printed directly beneath the QR/PDF417/Code128 graphic so staff can look up the pass via GET /api/v1/scans/pass?barcode=... if your screen is cracked.

Important: If you see an expired or voided badge across your pass (pass status: VOIDED or EXPIRED), 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_SCAN or EXPIRED).

Still need assistance? See Add a Pass to Your Wallet or reach out via Contact Support.

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.