Skip to content
Help Center Guide · Certificates & CredentialsOnboarding Phase 2
3 min readVerified 2026-11-16

Google Wallet Configuration

Understand managed Google Wallet Issuer ID provisioning vs. custom Issuer configuration and Android field overrides in the Visual Editor.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Template Editor — Pass type & layout variant (Zoomed)

Select the underlying pass structure (Discount Coupon, Store / Loyalty Card, Event Ticket, Generic Pass, or Boarding Pass) and layout variant.

Overview: Managed vs. Custom Google Wallet Issuer Setup

Unlike Apple Wallet's per-merchant certificate requirement, Passinstance provides Managed Google Wallet Issuer Infrastructure out of the box so you can publish and distribute Android passes immediately during onboarding (PUT /api/v1/onboarding/wallet-setup). For enterprise brands that require ownership of their own Google Pay & Wallet Console Issuer ID or custom Google Smart Tap contactless keys, Passinstance also supports binding a dedicated Google Cloud Service Account (POST /api/v1/google-wallet/setup).

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
GOOGLE WALLET ISSUER & SERVICE ACCOUNT SETUP
STAGE 01 OPTION A: MANAGED PASSINSTANCE ISSUER (DEFAULT)
Zero Google Cloud setup required
Activated automatically during Onboarding (PUT/api/v1/onboarding/wallet-setup)
Passinstance signs Save JWTs & manages walletobjects REST calls automatically
STAGE 02 OPTION B: CUSTOM ENTERPRISE ISSUER CONFIGURATION
1
Google Pay & Wallet Console (pay.google.com/business/console)
Copy 19-digit numeric issuerId (e.g., 3388000000022194812)
Configure Smart Tap collectorId (if using contactless NFC redemption)
2
Google Cloud Console (console.cloud.google.com)
Enable "Google Wallet API" (walletobjects.googleapis.com)
Create Service Account & export JSON key (private_key, client_email)
3
Authorize Service Account in Google Pay & Wallet Console
Invite client_email with Developer / Admin access
4
Provision in Passinstance (POST/api/v1/google-wallet/setup)
Encrypts Service Account JSON in encrypted storage & verifies API connectivity

Prerequisites: When configuring a Custom Google Wallet Issuer ID, you must invite the Google Cloud Service Account's client_email inside the Google Pay & Wallet Business Console -> Users with Developer permissions. Without this IAM binding, Google's walletobjects API returns 403 Forbidden when Passinstance attempts to create Classes or Objects.

Comparing Managed vs. Custom Google Issuer Mode

CapabilityManaged Passinstance IssuerCustom Enterprise Issuer ID
Setup TimeInstant (0 minutes)~15 minutes (Google Cloud + Business Console)
Brand Name & Logo on CardFully customized per template (issuerName, programLogo)Fully customized per template (issuerName, programLogo)
Google Pay & Wallet Console AccessManaged by PassinstanceDirect access to your own Google Business Console
Google Smart Tap NFC (NFC_SMART_TAP)Uses workspace/reader configurationSupports your own custom smartTapMerchantId & collectorId
Callback Webhook (/api/v1/wallet/callback)Pre-configured automaticallyConfigured automatically on class creation

Google Wallet Setup & Template Activation API (Google Wallet Setup API)

All Google Wallet issuer and template provisioning endpoints live under /api/v1/google-wallet:

MethodEndpoint PathPermission RequiredDescription
POST/api/v1/google-wallet/setupwallet:manage, certificates:manageProvisions a Google Wallet issuer account and optional Smart Tap collector ID using your workspace company details.
GET/api/v1/google-wallet/statuswallet:read / wallet:manageReturns { isConfigured, collectorId } indicating whether Google Wallet and Smart Tap are provisioned.
POST/api/v1/google-wallet/repair-callbackswallet:manage, certificates:manageRe-syncs missing /api/v1/wallet/callback webhook URLs across published Google Wallet Classes.
POST/api/v1/google-wallet/templates/:templateId/activatewallet:manage, certificates:manageActivates Google Wallet class provisioning for a specific template.
POST/api/v1/google-wallet/templates/:templateId/deactivatewallet:manage, certificates:manageDisables Google Wallet support for a specific template.
GET/api/v1/google-wallet/templates/:templateId/statuswallet:manage, certificates:readReturns { isEnabled, issuerId } for the target template.

Example: Initializing Google Wallet Issuer Setup

BASH
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>

Response (201 Created):

JSON
{
  "issuerId": "3388000000022194812",
  "googlePayAccount": {
    "accountIdentifier": "3388000000022194812",
    "collectorId": "50992104"
  },
  "smartTapMerchantData": {
    "smartTapMerchantId": "50992104"
  }
}

Checking status afterward via GET /api/v1/google-wallet/status returns { "isConfigured": true, "collectorId": "50992104" }, and individual passes expose googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION).

Best Practices During Template Setup

  1. 1
    Choose the Matching Google Pass Category: Inside Edit Template -> Pass Types, match your program to Loyalty (LoyaltyClass), Offer (OfferClass), Gift Card (GiftCardClass), Event Ticket (EventTicketClass), or Generic Pass (GenericClass) — Google Wallet classes cannot change resource type once published.
  2. 2
    Test Android Previews Explicitly: Toggle between Apple Wallet and Google Wallet in the live preview panel because image aspect ratios (androidBackground wide hero banner vs. square googlePayLogo crop) and field truncation rules differ between platforms.
  3. 3
    Use Android Overrides: Set tailored Android field labels and values via the Inspector when an Apple layout slot does not map 1:1 on Android.

See Google Wallet and Google Smart Tap for class/object and NFC specifications.

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.