Google Wallet.

Early Access: The Google Wallet integration is available for early access. Try it out and share your feedback. Your input shapes how this feature evolves. Some functionality may change as we refine the experience.

Google Wallet integration lets your members save their loyalty cards, stamp cards, vouchers, and prepaid passes to Google Wallet. Passes update when points change, stamps are earned, vouchers are redeemed, or pass visits are ticked off. No app download required.

What It Does

How It Works

1. Admin enables the system-wide feature flag (FEATURE_GOOGLE_WALLET=true) and configures credentials
2. Admin grants Google Wallet permission to a partner via the partner settings
3. Partner toggles "Google Wallet" on for individual cards, stamp cards, vouchers, or prepaid passes
4. Members see the "Add to Google Wallet" button and save the pass to their phone
5. System automatically updates passes when data changes (points earned, stamps added, voucher redeemed)

Roles & Permissions

Admin Setup

1. Google Cloud Prerequisites

Before configuring Reward Loyalty, you need a Google Cloud project with a service account.

Create a project and enable the API:

1. Go to the Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable the Google Wallet API: navigate to APIs & Services → Library, search for "Google Wallet API", and click Enable

Create a service account:

4. Open the ☰ navigation menu (top-left hamburger icon) and go to IAM & Admin → Service Accounts. Do not use the "Create credentials" button on the API page. That creates the wrong credential type.
5. Click Create Service Account
6. Enter a name (e.g. reward-loyalty-wallet) and click Create and Continue
7. On the "Grant this service account access" step, skip it and click Continue. No roles are needed. The Wallet API uses its own issuer-level permissions.
8. On the "Grant users access" step, skip it and click Done. This controls who else in your org can manage this service account.

Download the JSON key:

9. You are now on the service accounts list. Click on the service account you created.
10. Go to the Keys tab
11. Click Add key → Create new key
12. In the dialog that appears, select JSON and click Create
13. A .json file downloads to your computer. Back up this file. You cannot download it again.
14. Open the JSON file and note the client_email value (e.g. [email protected]). You will need this in the next step.

For the official Google guide, see Google Wallet Prerequisites.

2. Google Wallet Issuer Account

Get your Issuer ID:

1. Go to the Google Pay & Wallet Console
2. Sign in with the Google account that owns your Cloud project
3. In the left sidebar, click Google Wallet API (not Google Pay API). If this is your first time, click Build your first pass to initialize the Wallet API section.
4. Your Issuer ID appears at the top of the page next to the heading. It is a long numeric value like 3388000000023138604. This is not the Merchant ID shown on the main dashboard (that alphanumeric code is for Google Pay, not Google Wallet).

Authorize your service account:

5. In the left sidebar, click Users
6. Click Invite a user
7. Paste the service account email you noted in step 14 (the client_email from your JSON key file)
8. Set the Access level to Admin
9. Click Invite

Add test accounts (demo mode only):

7. While your account is in demo mode, only authorized test accounts can see passes on their phones. Go back to Google Wallet API in the left sidebar, click Set up test accounts, and add the personal Gmail addresses of anyone who needs to test. Console admins and developers can always test without being added here.
8. Once you request and receive publishing access, all users can see passes and this step is no longer needed.

3. Configure Credentials

You need to give Reward Loyalty the JSON key file you downloaded. There are two ways to do this. Pick one.

Option A: Inline JSON in .env (recommended for Docker, cloud, and managed hosting)

1. Open the downloaded .json file in a text editor
2. Remove all line breaks so the entire JSON is on one line. Most editors have a "Join Lines" command, or you can run this in a terminal:

cat ~/Downloads/your-key-file.json | tr -d '\n' | tr -s ' '

3. Copy the single-line result and paste it into your .env file, wrapped in single quotes:

GOOGLE_WALLET_CREDENTIALS_JSON='{"type":"service_account","project_id":"your-project","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","client_email":"...","client_id":"...","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/...","universe_domain":"googleapis.com"}'

The single quotes are required. Without them, the double quotes inside the JSON break the .env parser and cause a 500 error. Do not replace the internal double quotes. JSON requires them. The \n characters inside private_key are literal escape sequences and should stay as-is.

Option B: File path (simpler for traditional server hosting)

1. Create the credentials directory inside your Reward Loyalty installation:

mkdir -p storage/credentials

2. Copy the downloaded .json file into that directory:

cp ~/Downloads/your-key-file.json storage/credentials/google-wallet-sa.json

3. Add the path to your .env file:

GOOGLE_WALLET_CREDENTIALS_PATH=storage/credentials/google-wallet-sa.json

The path is relative to your project root. Do not place the file in the public/ directory.

Remaining .env variables

# Enable the feature
FEATURE_GOOGLE_WALLET=true

# Your issuer ID from the Google Pay & Wallet Console
GOOGLE_WALLET_ISSUER_ID=3388000000012345678

If both GOOGLE_WALLET_CREDENTIALS_JSON and GOOGLE_WALLET_CREDENTIALS_PATH are set, the inline JSON takes priority.

After updating .env, clear the config cache:

php artisan config:clear

4. Grant Partner Permission

After configuring credentials, you need to grant Google Wallet access to each partner individually.

1. Log in as Admin
2. Go to Administration → Partners
3. Click Edit on the partner you want to enable
4. Go to the Permissions tab
5. Enable the Google Wallet toggle
6. Save

The partner can now see the Google Wallet toggle on their cards. Repeat for each partner who needs access.

5. Verify Configuration

Go to Settings → Integrations in the admin sidebar. The Google Wallet status card shows:

• Configured: issuer ID and credentials are set. The integration is ready to use.
• Not Configured: one or both are missing. Check your .env file and run php artisan config:clear.

Partner Guide

Enabling Google Wallet on a Card

Once your admin has granted Google Wallet permission to your account, you can enable it on individual cards.

1. Go to Loyalty Cards, Stamp Cards, or Vouchers
2. Click Edit on the card you want to enable
3. Go to the Details tab
4. Find the Google Wallet toggle and switch it on
5. Save

If you do not see the Google Wallet toggle, your admin has not yet enabled Google Wallet permission for your account. Contact your administrator.

Members who are enrolled in this card will now see an "Add to Google Wallet" button on their card view.

Pass Design — How Your Card Appears in Google Wallet

Google Wallet passes reuse the visual elements you already configured on your cards. No extra design work is needed. Here is exactly which fields are used for each pass type.

Loyalty Cards

┌─────────────────────────────────────┐
│  [Logo]  Partner Name               │  ← Logo image + partner name
│                                     │
│  Card Title                         │  ← Card title
│                                     │
│  points                             │
│  2,000                              │  ← Current point balance
│                                     │
│       ┌───────────┐                 │
│       │  QR Code  │                 │  ← Staff earn-points URL
│       └───────────┘                 │
│    Member Identifier                │  ← Member code
│─────────────────────────────────────│
│   Background Image                  │  ← Background image (hero)
│                                     │
└─────────────────────────────────────┘

Logo and background image are the images you upload on the card's Media tab. See Creating Cards for image requirements.

Stamp Cards

┌─────────────────────────────────────┐
│  [Logo]  Partner Name               │  ← Logo image + partner name
│                                     │
│  Partner Name                       │  ← Subheader
│  Stamp Card Title                   │  ← Card title (large)
│                                     │
│       ┌───────────┐                 │
│       │  QR Code  │                 │  ← Staff stamp-claim URL
│       └───────────┘                 │
│                                     │
└─────────────────────────────────────┘

  Progress: 3 / 10                     ← Current stamps / required
  Reward: Free Coffee                  ← Reward title

Stamp cards use Google's Generic pass type, which does not support a hero image. Only the background color and logo appear. See Designing Your Cards for logo specifications.

Prepaid Passes

┌─────────────────────────────────────┐
│  [Logo]  Partner Name               │  ← Logo image + partner name
│                                     │
│  Partner Name                       │  ← Subheader
│  Pass Name                          │  ← e.g. "10-Visit Wash Pass"
│                                     │
│       ┌───────────┐                 │
│       │  QR Code  │                 │  ← Staff use-pass URL
│       └───────────┘                 │
│                                     │
└─────────────────────────────────────┘

  Visits left: 6 / 10                  ← Remaining / total (or Unlimited)
  Expires: Jul 10, 2026                ← Valid until date (if set)

Prepaid passes use Google's Generic pass type, like stamp cards, so no hero image appears. Each sold pass is its own Google Wallet object: a member holding two passes of the same product can save both. Enable the toggle per pass product on its Details tab.

Vouchers

┌─────────────────────────────────────┐
│  [Logo]  Partner Name               │  ← Logo + partner name
│                                     │
│  Voucher Title                      │  ← e.g. "Free Pastry"
│                                     │
│       ┌───────────┐                 │
│       │  QR Code  │                 │  ← Staff redemption URL
│       └───────────┘                 │
│    Voucher Code                     │  ← e.g. CAFDCBAB6
│─────────────────────────────────────│
│   Background Image                  │  ← Background image (hero)
│                                     │
└─────────────────────────────────────┘

  Expires: Feb 1, 2027                 ← Valid until date
  From: The Daily Grind                ← Partner name

Logo and background image are the images you upload on the voucher's Media tab. See Voucher Card Design for image requirements.

Design Tips for Google Wallet

• Upload a logo. Passes without a logo show a generic icon or the first letter of your business name. A proper logo makes your pass instantly recognizable.
• Choose a good background color. This is the most visible element — it fills the top half (or full card for stamp cards). Use your brand color.
• Add a background image. For loyalty cards and vouchers, the background image appears as a large hero below the QR code. Use a high-quality, relevant photo (product shots, your storefront, lifestyle imagery).
• Images must be publicly accessible. Google fetches your images from your server. Images served from localhost or private networks will not load. See Local Development below.

What Members See

• A localized "Add to Google Wallet" button on every card, stamp card, voucher, or prepaid pass that has Google Wallet enabled
• The button is always visible, even before the member has followed or enrolled in the card
• Tapping the button auto-enrolls the member (if not already enrolled) and opens Google Wallet
• The pass shows the card name, current points, stamp progress, or visits left, and a QR code
• Pass data updates when points are earned, stamps are collected, or a voucher is redeemed

No enrollment or transactions are required to see the button. The member does not need to follow the card first. Clicking the button handles enrollment automatically.

When the Button Does Not Appear

The "Add to Google Wallet" button has three conditions, all of which must be met:

1. System feature flag: FEATURE_GOOGLE_WALLET=true in .env
2. Partner permission: admin has granted Google Wallet permission to the partner
3. Card toggle: partner has enabled Google Wallet on the specific card

If the button is missing, check these three conditions in order.

Button Behavior by Member State

Disabling Google Wallet

Toggle the switch off and save. All issued passes for that card will be revoked. Members' saved passes will show as inactive.

Member Guide

Saving a Card to Google Wallet

1. Open any loyalty card, stamp card, or voucher
2. Look for the "Add to Google Wallet" button below the card
3. Tap the button
4. If you are not logged in, you will be asked to log in first
5. Confirm to save the pass in Google Wallet

Viewing Your Pass

• Open the Google Wallet app on your phone or visit wallet.google.com on desktop
• Your loyalty card, stamp card, or voucher appears with current details
• Data updates automatically when you earn points, collect stamps, or redeem a voucher

Pass States

Testing

Test Mode Checklist

1. Set FEATURE_GOOGLE_WALLET=true in .env
2. Configure your issuer ID and credentials
3. Create a test card and enable Google Wallet
4. Enroll a test member
5. Verify the "Add to Google Wallet" button appears
6. Save the pass and check it in Google Wallet
7. Earn points or stamps and verify the pass updates

Common Issues

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:

• Actually 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 & Bug Reports

If you encounter issues with Google Wallet passes:

1. Note the specific card/stamp/voucher and member involved
2. Check the application logs for Google Wallet entries
3. Report the issue through your usual support channel, including:
   • What you expected to happen
   • What actually happened
   • The card type (loyalty, stamp, or voucher)
   • Whether the pass was ever saved successfully

Technical Details