Overview: Two-Tier Class & Object Architecture
Unlike Apple Wallet's downloadable .pkpass binary archive, Google Wallet operates on a cloud-hosted two-tier data model managed via the Google Wallet REST API (walletobjects/v1):
-
1
Wallet Class (Template Layer): Defines shared visual branding, issuer metadata, program logos, layout structure, and callback URLs across all passholders of a template (e.g.,
LoyaltyClass,EventTicketClass,OfferClass,GiftCardClass,GenericClass). -
2
Wallet Object (Pass Instance Layer): Represents an individual customer's credential referencing its parent
classId(e.g.,LoyaltyObject,EventTicketObject,OfferObject,GiftCardObject,GenericObject), holding the passholder's unique barcode, points balance, tier status, and Smart Tap payload.
Mapping Passinstance Programs to Google Wallet Classes & Objects
Passinstance's factory adapters automatically map your template configuration to the corresponding Google Wallet resource pair:
| Passinstance Program | Google Class Resource | Google Object Resource | Primary Specialized Fields |
|---|---|---|---|
| Loyalty & Stamp Cards | LoyaltyClass | LoyaltyObject | loyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier |
| Coupons & Vouchers | OfferClass | OfferObject | redemptionChannel, provider, validTimeInterval, barcode |
| Gift & Prepaid Cards | GiftCardClass | GiftCardObject | cardNumber, pin, balance (micros + currencyCode), balanceUpdateTime |
| Event Tickets | EventTicketClass | EventTicketObject | seatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen |
| Membership & IDs | GenericClass | GenericObject | cardTitle, subheader, header, textModulesData, imageModulesData |
Important: Even if a customer signs into their Google Account across multiple Android devices, Google Wallet binds the credential to a single canonical
<issuerId>.<objectId>. Passinstance deduplicates at the Object level and counts this as 1 active Google Wallet pass.
Signed JWT Save Links & Callback Webhooks
1. RS256 Signed Save to Google Wallet JWT
When a passholder opens a smart link on Android, Passinstance constructs and signs a JSON Web Token with your Google Cloud Service Account private key and redirects to https://pay.google.com/gp/v/save/<jwt>:
{
"iss": "wallet-signer@passinstance-prod.iam.gserviceaccount.com",
"aud": "google",
"typ": "savetowallet",
"iat": 1763218800,
"origins": ["https://app.passinstance.com"],
"payload": {
"loyaltyObjects": [
{
"id": "3388000000022194812.pass_c41a8d20",
"classId": "3388000000022194812.cls_7b9e4c12",
"state": "ACTIVE",
"accountId": "CUST-88412",
"accountName": "Alex Rivera",
"loyaltyPoints": {
"label": "Points",
"balance": { "int": 1450 }
},
"barcode": {
"type": "QR_CODE",
"value": "PI-8849-2026-X9",
"alternateText": "PI-8849-2026-X9"
}
}
]
}
}
2. Google Wallet Install & Removal Callback (POST /api/v1/wallet/callback)
Every Google Wallet Class provisioned by Passinstance sets callbackOptions.url to POST /api/v1/wallet/callback. Whenever an Android user saves a pass to Google Wallet or removes it from their device, Google dispatches a signed callback payload:
POST /api/v1/wallet/callback
{
"classId": "3388000000022194812.cls_7b9e4c12",
"objectId": "3388000000022194812.pass_c41a8d20",
"eventType": "save",
"expTimeMillis": 1763219100000,
"nonce": "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
}
-
eventType: "save": Records the active Google Wallet installation, incrementsinstalledDevices, and fires thePASS_INSTALLEDwebhook/workflow trigger. -
eventType: "del": Marks the Google Wallet object uninstalled and decrements active pass usage counters.
Live Field Overrides for Android
Because Google Wallet renders passes using a vertical scrolling card layout (header, cardTitle, and two-column textModulesData rows) rather than Apple Wallet's fixed front/back flip card, you can configure Android Overrides in the Visual Editor Inspector for any field or image asset (googlePayLogo, androidBackground, androidLogo).
Learn more at Google Wallet Platform, Google Wallet Configuration, and Google Smart Tap.
