Troubleshooting.
Test the Google Wallet flow, fix a button that does not appear, and understand the local-development limits.
Jul 21, 2026
Testing
Test mode checklist
- Make sure a plan includes Google Wallet (Gold and Platinum by default), or grant it to the partner on the Permissions tab
- Configure your issuer ID and credentials (in Settings → Integrations or in
.env) - Create a test card and enable Google Wallet
- Enroll a test member
- Verify the "Add to Google Wallet" button appears
- Save the pass and check it in Google Wallet
- Earn points or stamps and verify the pass updates
Common issues
| Problem | Solution |
|---|---|
| Button doesn't appear | Check all three conditions: platform credentials, plan entitlement (or per-partner grant), card toggle |
| "Google Wallet credentials not configured" | Verify the issuer ID and credential path/JSON in Settings → Integrations, or GOOGLE_WALLET_ISSUER_ID and the credential path/JSON in .env |
| "not a valid id" when clicking button | The pass was never created on Google's servers. Check the logs for provisioning errors. Most common cause: image URLs are not publicly accessible (see local development note below). Also verify your GOOGLE_WALLET_ISSUER_ID matches the Issuer ID in the Google Pay & Wallet Console. |
| "Image cannot be loaded" in logs | Google needs to fetch card images from a public URL. Local development URLs like http://localhost or http://app.test will fail. Use a tunnel (ngrok, Expose) or test on a publicly accessible staging server. |
| Pass doesn't update after earning points/stamps | If you use the sync queue driver (default), updates happen inline. If you use database or redis, make sure your queue worker processes the google-wallet queue: php artisan queue:work --queue=default,google-wallet |
| Pass shows wrong data | Trigger a manual update by toggling the card off and on |
Local development
Google Wallet provisioning requires a publicly accessible server. Google's API fetches card images (logo, background) from your server. On local development, this fails because URLs like http://app.test are not reachable by Google.
What works locally:
- Configuring credentials and issuer ID
- Seeing the "Add to Google Wallet" button on the page
- Verifying the button generates a valid JWT
What requires a public URL:
- Saving a pass to Google Wallet (Google needs to fetch images)
- Pass provisioning (class and object creation)
To test the full flow, either deploy to a staging server or use a tunnel tool like ngrok to expose your local server.
Feedback and bug reports
If you encounter issues with Google Wallet passes:
- Note the specific card/stamp/voucher and member involved
- Check the application logs for
Google Walletentries - Report the issue through your usual support channel, including:
- What you expected to happen
- What happened
- The card type (loyalty, stamp, or voucher)
- Whether the pass ever reached Google Wallet
Technical details
| Detail | Value |
|---|---|
| Queue | google-wallet (optional, only relevant if you run a dedicated queue worker with database or redis driver) |
| Retry policy | 3 attempts with exponential backoff (10s, 30s, 60s) |
| Save flow | Synchronous provisioning with async fallback. If Google's servers respond within the timeout, the system redirects the member to Google Wallet. If provisioning times out, the system queues the job in the background and shows a retry message |
| Pass types | LoyaltyObject (loyalty cards), GenericObject (stamp cards and prepaid passes), OfferObject (vouchers) |
| QR codes | Each pass contains a staff-facing URL (earn points, add stamps, use a pass, or redeem a voucher) |
| Image source | Google fetches the logo and background images from your server, so they must be publicly accessible |