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).
Prerequisites: When configuring a Custom Google Wallet Issuer ID, you must invite the Google Cloud Service Account's
client_emailinside the Google Pay & Wallet Business Console -> Users with Developer permissions. Without this IAM binding, Google'swalletobjectsAPI returns403 Forbiddenwhen Passinstance attempts to create Classes or Objects.
Comparing Managed vs. Custom Google Issuer Mode
| Capability | Managed Passinstance Issuer | Custom Enterprise Issuer ID |
|---|---|---|
| Setup Time | Instant (0 minutes) | ~15 minutes (Google Cloud + Business Console) |
| Brand Name & Logo on Card | Fully customized per template (issuerName, programLogo) | Fully customized per template (issuerName, programLogo) |
| Google Pay & Wallet Console Access | Managed by Passinstance | Direct access to your own Google Business Console |
Google Smart Tap NFC (NFC_SMART_TAP) | Uses workspace/reader configuration | Supports your own custom smartTapMerchantId & collectorId |
Callback Webhook (/api/v1/wallet/callback) | Pre-configured automatically | Configured 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:
| Method | Endpoint Path | Permission Required | Description |
|---|---|---|---|
| POST | /api/v1/google-wallet/setup | wallet:manage, certificates:manage | Provisions a Google Wallet issuer account and optional Smart Tap collector ID using your workspace company details. |
| GET | /api/v1/google-wallet/status | wallet:read / wallet:manage | Returns { isConfigured, collectorId } indicating whether Google Wallet and Smart Tap are provisioned. |
| POST | /api/v1/google-wallet/repair-callbacks | wallet:manage, certificates:manage | Re-syncs missing /api/v1/wallet/callback webhook URLs across published Google Wallet Classes. |
| POST | /api/v1/google-wallet/templates/:templateId/activate | wallet:manage, certificates:manage | Activates Google Wallet class provisioning for a specific template. |
| POST | /api/v1/google-wallet/templates/:templateId/deactivate | wallet:manage, certificates:manage | Disables Google Wallet support for a specific template. |
| GET | /api/v1/google-wallet/templates/:templateId/status | wallet:manage, certificates:read | Returns { isEnabled, issuerId } for the target template. |
Example: Initializing Google Wallet Issuer Setup
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>
Response (201 Created):
{
"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
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
Test Android Previews Explicitly: Toggle between Apple Wallet and Google Wallet in the live preview panel because image aspect ratios (
androidBackgroundwide hero banner vs. squaregooglePayLogocrop) and field truncation rules differ between platforms. -
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.
