Skip to content
Help Center Guide · Wallet Integrations
3 min readVerified 2026-11-16

Google Wallet

How Passinstance provisions Generic, Loyalty, Offer, Gift Card, and Event Ticket Classes/Objects via signed Save JWT links.

In This Guide

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. 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. 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.
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
GOOGLE WALLET CLASS/OBJECT & JWT SAVE PIPELINE
STAGE 01 PHASE 1: TEMPLATE PUBLISHCLASS PROVISIONING
Passinstance Template Published (POST/api/v1/templates/:id/publish)
Google Wallet Sync upserts <issuerId>.<templateClassId> via Google REST (LoyaltyClass | EventTicketClass | OfferClass | GiftCardClass)
STAGE 02 PHASE 2: PASS ISSUANCE & RS256 SAVE JWT GENERATION
1
Provision or embed <issuerId>.<passObjectId> (LoyaltyObject, etc.)
2
Sign JWT claims (iss, aud: "google", typ: "savetowallet", payload) using Google Cloud Service Account RSA private key (RS256)
3
Return Save URL: https://pay.google.com/gp/v/save/<signed_jwt>
User Saves / Removes Pass
STAGE 03A Google Cloud invokes Passinstance
webhook: POST/api/v1/wallet/callback
Event: eventType: "save" | "del"
Updates active install telemetry
Server-Side Pass Mutation
STAGE 03B Passinstance executes REST PATCH
on walletobjects/v1/...Object
Google Play Services syncs live card on Android phone instantly

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 ProgramGoogle Class ResourceGoogle Object ResourcePrimary Specialized Fields
Loyalty & Stamp CardsLoyaltyClassLoyaltyObjectloyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier
Coupons & VouchersOfferClassOfferObjectredemptionChannel, provider, validTimeInterval, barcode
Gift & Prepaid CardsGiftCardClassGiftCardObjectcardNumber, pin, balance (micros + currencyCode), balanceUpdateTime
Event TicketsEventTicketClassEventTicketObjectseatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen
Membership & IDsGenericClassGenericObjectcardTitle, 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.

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>:

JSON
{
  "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:

JSON
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, increments installedDevices, and fires the PASS_INSTALLED webhook/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.

Related Product & Developer Documentation

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.