Skip to content
Hilfecenter-Anleitung · Wallet-Integrationen
2 Min. LesezeitGeprüft 2026-11-16

Google Wallet

Wie Passinstance Generic-, Loyalty-, Offer-, Gift-Card- und Event-Klassen/Objekte über signierte Save-JWT-Links ausgibt.

In dieser Anleitung

Überblick: Zweistufige Class- & Object-Architektur

Anders als das herunterladbare .pkpass-Binärarchiv von Apple Wallet arbeitet Google Wallet auf einem cloudgehosteten zweistufigen Datenmodell, das über die Google Wallet REST-API (walletobjects/v1) gesteuert wird:

  1. 1
    Wallet Class (Vorlagenebene): Definiert gemeinsames visuelles Branding, Aussteller-Metadaten, Programm-Logos, Layoutstruktur und Callback-URLs für alle Pässe einer Vorlage (z. B. LoyaltyClass, EventTicketClass, OfferClass, GiftCardClass, GenericClass).
  2. 2
    Wallet Object (Pass-Instanzebene): Repräsentiert den Ausweis einer einzelnen Kundin oder eines einzelnen Kunden mit Verweis auf die übergeordnete classId (z. B. LoyaltyObject, EventTicketObject, OfferObject, GiftCardObject, GenericObject) inklusive individuellem Barcode, Punktestand, Stufenstatus und Smart-Tap-Payload.
SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
GOOGLE-WALLET-CLASS/OBJECT- & JWT-SAVE-PIPELINE
STUFE 01 PHASE 1: VORLAGE VERÖFFENTLICHENCLASS-BEREITSTELLUNG
Passinstance-Vorlage veröffentlicht (POST/api/v1/templates/:id/publish)
Google Wallet Sync erstellt/aktualisiert <issuerId>.<templateClassId> über Google REST (LoyaltyClass | EventTicketClass | OfferClass | ...)
STUFE 02 PHASE 2: PASS-AUSGABE & RS256-SAVE-JWT-ERZEUGUNG
1
<issuerId>.<passObjectId> (LoyaltyObject etc.) bereitstellen o. einbetten
2
JWT-Claims (iss, aud: "google", typ: "savetowallet", payload) signieren mit dem RSA-Private-Key des Google-Cloud-Dienstkontos (RS256)
3
Save-URL zurückgeben: https://pay.google.com/gp/v/save/<signed_jwt>
Nutzende speichern / entfernen Pass
STUFE 03A Google Cloud ruft Passinstance-Webhook
auf: POST/api/v1/wallet/callback
Event: eventType: "save" | "del"
Aktualisiert Installations-Telemetrie
Serverseitige Pass-Änderung
STUFE 03B Passinstance führt REST-PATCH auf
walletobjects/v1/...Object aus
Google Play Services synchroni- siert Android-Karte sofort

Zuordnung von Passinstance-Programmen zu Google-Wallet-Classes & -Objects

Passinstances Factory-Adapter bilden Ihre Vorlagenkonfiguration automatisch auf das passende Google-Wallet-Ressourcenpaar ab:

Passinstance-ProgrammGoogle-Class-RessourceGoogle-Object-RessourceZentrale Spezialfelder
Treue- & StempelkartenLoyaltyClassLoyaltyObjectloyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier
Coupons & GutscheineOfferClassOfferObjectredemptionChannel, provider, validTimeInterval, barcode
Geschenk- & Prepaid-KartenGiftCardClassGiftCardObjectcardNumber, pin, balance (micros + currencyCode), balanceUpdateTime
Event-TicketsEventTicketClassEventTicketObjectseatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen
Mitgliedschaften & AusweiseGenericClassGenericObjectcardTitle, subheader, header, textModulesData, imageModulesData

Wichtig: Selbst wenn eine Kundin oder ein Kunde mit demselben Google-Konto auf mehreren Android-Geräten angemeldet ist, bindet Google Wallet den Ausweis an eine einzige kanonische <issuerId>.<objectId>. Passinstance dedupliziert auf Object-Ebene und zählt dies als 1 aktiven Google-Wallet-Pass.

1. RS256-signiertes „Zu Google Wallet hinzufügen“-JWT

Öffnet eine Person einen Smart-Link unter Android, erstellt und signiert Passinstance ein JSON Web Token mit dem Private Key Ihres Google-Cloud-Dienstkontos und leitet auf https://pay.google.com/gp/v/save/<jwt> weiter:

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-Installations- & Entfernungs-Callback (POST /api/v1/wallet/callback)

Jede von Passinstance bereitgestellte Google-Wallet-Class setzt callbackOptions.url auf POST /api/v1/wallet/callback. Sobald jemand unter Android einen Pass in Google Wallet speichert oder vom Gerät entfernt, sendet Google ein signiertes 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": Erfasst die aktive Google-Wallet-Installation, erhöht installedDevices und löst den Webhook-/Workflow-Trigger PASS_INSTALLED aus.
  • eventType: "del": Markiert das Google-Wallet-Objekt als deinstalliert und reduziert den Zähler aktiver Pässe.

Live-Feldüberschreibungen für Android

Da Google Wallet Pässe in einem vertikal scrollbaren Kartenlayout (header, cardTitle und zweispaltige textModulesData-Zeilen) statt in Apple Wallets fixer Vorder-/Rückseiten-Klappkarte darstellt, können Sie im Inspektor des visuellen Editors für jedes Feld oder Bild-Asset (googlePayLogo, androidBackground, androidLogo) gezielte Android Overrides hinterlegen.

Erfahren Sie mehr unter Google-Wallet-Plattform, Google-Wallet-Konfiguration sowie Google Smart Tap.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.