Google Wallet API

Mit der Google Wallet API können Sie Google Wallet-Pässe programmgesteuert erstellen, aktualisieren, auflisten und verwalten. Sie unterstützt dieselben Operationen, die der Pass-Builder im Control Panel durchführt.

Verwenden Sie sie, um Kundenkarten, Angebote, Geschenkkarten, Veranstaltungstickets, Flug-Bordkarten, Fahrkarten und generische Pässe auszustellen und um Live-Updates an Pässe zu senden, die bereits auf den Geräten Ihrer Benutzer gespeichert sind.

Voraussetzung: Google Wallet-Konfiguration

Bevor Sie Pässe für eine Anwendung erstellen können, müssen eine Google Wallet Issuer ID und ein Dienstkontoschlüssel für diese Anwendung im Pushwoosh Control Panel konfiguriert sein. Ohne diese schlagen create- und update-Anfragen fehl. Siehe Konfiguration von Google Wallet-Pässen für Android.

Basis-URL

https://apple-passkit.svc-nue.pushwoosh.com

Alle Endpunkte werden über HTTPS bereitgestellt. Anfragen und Antworten verwenden application/json, sofern nicht anders angegeben.

Authentifizierung

Jede Anfrage muss einen Authorization-Header mit Ihrem Pushwoosh API-Zugriffstoken enthalten:

Authorization: Token <api-token>

Das Konto, dem das Token gehört, muss auch Eigentümer der Anwendung sein, auf die sich applicationCode bezieht. Eine Anfrage für eine Anwendung, die zu einem anderen Konto gehört, gibt 403 Forbidden zurück.

Konventionen

• Feldnamen: JSON-Felder verwenden lowerCamelCase (zum Beispiel serialNumber, hexBackgroundColor, logoUrl).
• Nicht ausgefüllte Felder: Antworten enthalten alle Felder, auch wenn sie leer oder null sind.
• Identität: Die serialNumber wird immer vom Server zugewiesen, wenn ein Pass erstellt wird. Jeder Wert, den Sie bei der Erstellung senden, wird ignoriert. Die vollständige Google Wallet-Objekt-ID lautet {issuerId}.{serialNumber}.
• Bilder: logoUrl und heroImageUrl sind öffentliche HTTPS-URLs zu Bildern, die Google abruft – keine hochgeladenen Dateien.
• Pass-Stil: Genau ein Stilobjekt (generic, offer, loyalty, eventTicket, giftCard, flight oder transit) muss für einen Pass festgelegt werden. Der Stil kann nach der Erstellung nicht mehr geändert werden.

Fehlerantworten

HTTP-Status	Bedeutung
400 Bad Request	Ungültiges Argument – ein erforderliches Feld fehlt oder ist fehlerhaft.
401 Unauthorized	Fehlender oder ungültiger Authorization-Header.
403 Forbidden	Die Anwendung gehört nicht zum Konto des Aufrufers.
404 Not Found	Der Pass, die Vorlage oder die Anwendung wurde nicht gefunden.
503 Service Unavailable	Der Dienst ist ausgelastet oder vorübergehend nicht verfügbar.

Endpunkte

Methode	Pfad	Beschreibung
POST	/api/google/pass/validate	Eine Pass-Konfiguration validieren
POST	/api/google/pass/create	Ein neues Pass-Objekt erstellen und einen Speicherlink erhalten
POST	/api/google/pass/update/{serialNumber}	Einen bestehenden Pass aktualisieren; Google liefert die Änderung aus
GET	/api/google/pass/{applicationCode}/{serialNumber}/save-link	Einen „Zu Google Wallet hinzufügen“-Speicherlink erhalten
GET	/api/google/pass/{applicationCode}/{serialNumber}	Einen einzelnen Pass abrufen
GET	/api/google/passes	Alle Pässe für eine Anwendung auflisten
POST	/api/google/pass/{applicationCode}/{serialNumber}/state	Einen Pass aktivieren oder für ungültig erklären
DELETE	/api/google/pass/{applicationCode}/{serialNumber}	Einen Pass löschen
GET	/api/google/config	Die Google Wallet-Konfiguration der Anwendung abrufen
GET	/api/google/templates	Verfügbare Pass-Vorlagen auflisten
GET	/api/google/templates/{filename}	Eine einzelne Vorlage abrufen

Einen Pass erstellen

Erstellt die Pass-Klasse und das Objekt in Google Wallet und gibt dann die vom Server zugewiesene Seriennummer, die vollständige Objekt-ID und einen „Zu Google Wallet hinzufügen“-Speicherlink zurück.

POST /api/google/pass/create

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
pass	object	Ja	Das Pass-Objekt, das den Pass beschreibt. Genau ein Stil muss festgelegt sein.
userId	string	Ja	Die Pushwoosh User-ID, für die der Pass ausgestellt wird.
applicationCode	string	Ja	Der Pushwoosh-Anwendungscode.

Beispiel für eine Anfrage

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Antwort

Feld	Typ	Beschreibung
serialNumber	string	Vom Server zugewiesene eindeutige Identität des erstellten Passes.
objectId	string	Vollständige Google Wallet-Objekt-ID: {issuerId}.{serialNumber}.
saveLink	string	„Zu Google Wallet hinzufügen“-Link: https://pay.google.com/gp/v/save/{jwt}.
message	string	Ergebnismeldung.

Beispiel für eine Antwort

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

Einen Pass validieren

Überprüft eine Pass-Konfiguration anhand der Anforderungen von Google, ohne ihn zu erstellen. Nützlich vor dem Aufruf von create.

POST /api/google/pass/validate

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
pass	object	Ja	Das zu validierende Pass-Objekt.

Antwort

Feld	Typ	Beschreibung
valid	boolean	Ob der Pass die Validierung besteht.
errors	array of strings	Blockierende Probleme, die behoben werden müssen.
warnings	array of strings	Nicht blockierende Hinweise.

Einen Pass aktualisieren

Patcht das Pass-Objekt mit neuem Inhalt. Google liefert dann die aktualisierte Version an jedes Gerät, das den Pass gespeichert hat. Sendet optional eine Android-Benachrichtigung mit dem Update.

POST /api/google/pass/update/{serialNumber}

Pfadparameter

Parameter	Typ	Beschreibung
serialNumber	string	Die Seriennummer, die bei der Erstellung des Passes zurückgegeben wurde.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
updates	object	Ja	Das Pass-Objekt mit dem neuen Inhalt. Der Stil kann nicht geändert werden.
applicationCode	string	Ja	Der Pushwoosh-Anwendungscode.
notifyMessage	string	Nein	Wenn nicht leer, wird eine Android-Benachrichtigung mit diesem Text an alle gesendet, die den Pass gespeichert haben. Ein leerer Wert bedeutet ein stilles Update.
notifyOnUpdate	boolean	Nein	Fordert eine Benachrichtigung über eine Feldaktualisierung an. Nur loyalty-, eventTicket- und flight-Pässe benachrichtigen tatsächlich; andere Stile akzeptieren das Flag, senden aber nie eine Benachrichtigung. Benachrichtigungen werden nur innerhalb von 3 Stunden vor einer relevanten Startzeit ausgelöst, und Google begrenzt sie auf 3 Benachrichtigungen pro Pass pro 24 Stunden.

Zwei Möglichkeiten, bei einer Aktualisierung zu benachrichtigen

notifyMessage sendet eine benutzerdefinierte Android-Benachrichtigung an alle, die den Pass gespeichert haben, und funktioniert für jeden Pass-Stil. notifyOnUpdate bittet Google, eine eigene Feldaktualisierungs-Benachrichtigung zu senden, die nur für loyalty-, eventTicket- und flight-Pässe ausgelöst wird.

Antwort

Feld	Typ	Beschreibung
success	boolean	Ob die Aktualisierung erfolgreich war.
message	string	Ergebnismeldung.

Einen Speicherlink erhalten

Gibt einen „Zu Google Wallet hinzufügen“-Speicherlink für einen bereits erstellten Pass zurück. Das Pass-Objekt muss bereits existieren (erstellt über Einen Pass erstellen).

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

Antwort

Feld	Typ	Beschreibung
saveLink	string	https://pay.google.com/gp/v/save/{jwt}.

Teilen Sie den Link oder rendern Sie ihn als QR-Code

Platzieren Sie den saveLink hinter einem „Zu Google Wallet hinzufügen“-Button oder rendern Sie ihn mit einer beliebigen QR-Bibliothek als QR-Code. Wenn ein Benutzer ihn öffnet, fordert Google ihn auf, den Pass zu speichern und sein Gerät für Updates zu registrieren.

Einen Pass abrufen

Gibt einen einzelnen gespeicherten Pass zurück, einschließlich seines vollständigen Pass-Objekts.

GET /api/google/pass/{applicationCode}/{serialNumber}

Antwort

Gibt { "pass": { ... } } zurück, einen einzelnen Pass-Datensatz.

Pässe auflisten

Gibt eine paginierte, sortierte Liste der für eine Anwendung gespeicherten Pässe zurück.

GET /api/google/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
applicationCode	string	Ja	Der Pushwoosh-Anwendungscode.
orderBy	string	Nein	Sortierfeld: UPDATED (Standard) oder CREATED.
orderDirection	string	Nein	Sortierrichtung: DESC (Standard, neueste zuerst) oder ASC.
page	integer	Nein	Nullbasierter Seitenindex. Standard ist 0.
perPage	integer	Nein	Seitengröße. 0 oder weggelassen verwendet den Server-Standard.

Antwort

Feld	Typ	Beschreibung
passes	array of objects	Die aktuelle Seite der Pass-Datensätze.
page	integer	Der zurückgegebene Seitenindex.
perPage	integer	Die für diese Antwort verwendete Seitengröße.
total	integer	Gesamtzahl der Pässe für die Anwendung über alle Seiten hinweg.

Pass-Status festlegen

Aktiviert oder erklärt einen Pass für ungültig. Ein ungültiger (inaktiver) Pass wird in den Bereich Abgelaufene Pässe des Benutzers in Google Wallet verschoben; der Datensatz wird aufbewahrt, damit er reaktiviert werden kann.

POST /api/google/pass/{applicationCode}/{serialNumber}/state

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
active	boolean	Ja	true setzt den Pass auf ACTIVE; false erklärt ihn für ungültig (INACTIVE).

Antwort

Gibt bei Erfolg ein leeres Objekt {} zurück.

Einen Pass löschen

Erklärt den Pass in Google für ungültig und entfernt seinen gespeicherten Datensatz in Pushwoosh.

DELETE /api/google/pass/{applicationCode}/{serialNumber}

Ein gespeicherter Pass kann nicht zwangsweise entfernt werden

Google erlaubt nicht, einen bereits auf dem Gerät eines Benutzers gespeicherten Pass zu entfernen. Das Löschen erklärt den Pass für ungültig (er wird zu den Abgelaufenen Pässen verschoben) und löscht den Pushwoosh-Datensatz.

Antwort

Gibt bei Erfolg ein leeres Objekt {} zurück.

Konfiguration abrufen

Gibt den Konfigurationsstatus von Google Wallet für eine Anwendung zurück.

GET /api/google/config?applicationCode=XXXXX-XXXXX

Antwort

Feld	Typ	Beschreibung
hasServiceAccount	boolean	Ob ein Dienstkontoschlüssel konfiguriert ist.
issuerId	string	Die konfigurierte Google Pay & Wallet Console Issuer ID.
serviceAccountEmail	string	Die client_email des konfigurierten Dienstkontos.

Vorlagen

Listen Sie die verfügbaren Beispiel-Pass-Vorlagen auf oder rufen Sie eine als Pass-Objekt ab, das Sie als Ausgangspunkt verwenden können.

GET /api/google/templates – gibt { "templates": [ { "filename", "name", "description", "style" } ] } zurück.

GET /api/google/templates/{filename} – gibt { "template": { ...pass object... } } zurück.

Objektreferenz

Pass-Objekt

Feld	Typ	Beschreibung
serialNumber	string	Wird vom Server bei der Erstellung zugewiesen; identifiziert den Pass.
generic / offer / loyalty / eventTicket / giftCard / flight / transit	object	Der Pass-Stil. Genau einer muss festgelegt sein. Siehe die Stilobjekte unten.
hexBackgroundColor	string	Kartenhintergrundfarbe, #rrggbb.
logoUrl	string	Öffentliche HTTPS-URL des Logobildes. Erforderlich für Loyalty und Transit.
heroImageUrl	string	Öffentliche HTTPS-URL eines breiten Bannerbildes.
barcode	object	Barcode, der auf dem Pass angezeigt wird.
textModules	array	Textmodule, die in der Detailansicht angezeigt werden.
links	array	Linkmodule, die in der Detailansicht angezeigt werden.
expirationTime	string	ISO 8601-Zeit, zu der Google den Pass automatisch ablaufen lässt. Leer bedeutet kein Ablaufdatum.
appLink	object	App-Link: ein CTA-Button auf der Vorderseite des Passes.
locations	array	Standorte, die eine Geofence-Benachrichtigung auslösen (max. 10).
holdersPolicy	string	Wer den Pass speichern darf: ONE_USER_ALL_DEVICES (Standard), ONE_USER_ONE_DEVICE oder MULTIPLE_HOLDERS.

Generisches Objekt

Feld	Typ	Beschreibung
cardTitle	string	Erforderlich. Der Name des Ausstellers/Programms oben auf der Karte.
header	string	Erforderlich. Der Haupttitel der Karte.
subheader	string	Sekundärer Titel.
cardFields	array	Bis zu 6 Textmodule, die auf der Vorderseite angeheftet sind (bis zu 3 Reihen mit je 2).

Angebotsobjekt

Feld	Typ	Beschreibung
title	string	Erforderlich. Zum Beispiel 20% auf alles.
provider	string	Erforderlich. Der Name des Händlers.
details	string	Angebotsdetails.
finePrint	string	Allgemeine Geschäftsbedingungen.
redemptionChannel	string	ONLINE, INSTORE, BOTH (Standard) oder TEMPORARY_PRICE_REDUCTION.
issuerName	string	Wird auf den „ausgestellt von“-Oberflächen von Google angezeigt; Standard ist provider.

Loyalty-Objekt

Feld	Typ	Beschreibung
programName	string	Erforderlich. Erfordert logoUrl auf dem Pass.
accountName	string	Mitgliedsname, der auf der Karte angezeigt wird.
accountId	string	Mitglieds-ID, die auf der Karte angezeigt wird.
pointsLabel	string	Zum Beispiel Punkte. Wird nur mit einem Guthaben angezeigt.
pointsBalance	string	Das Punktguthaben.
rewardsTier	string	Zum Beispiel Gold.
rewardsTierLabel	string	Bezeichnung neben der Stufe; Standard ist Stufe.
issuerName	string	Standard ist programName.

Veranstaltungsticket-Objekt

Feld	Typ	Beschreibung
eventName	string	Erforderlich.
venueName / venueAddress	string	Details zum Veranstaltungsort.
startDateTime / endDateTime	string	ISO 8601 mit Offset (zum Beispiel 2026-07-01T19:30:00+02:00).
ticketHolderName / ticketNumber / ticketType	string	Details zum Inhaber und Ticket.
section / row / seat / gate	string	Sitzplatzdetails.
issuerName	string	Standard ist eventName.

Geschenkkartenobjekt

Feld	Typ	Beschreibung
merchantName	string	Erforderlich.
cardNumber	string	Erforderlich.
pin	string	Karten-PIN.
balance	string	Dezimalbetrag, zum Beispiel 25.00. Erfordert balanceCurrency.
balanceCurrency	string	ISO 4217 Währungscode, zum Beispiel USD.
issuerName	string	Standard ist merchantName.

Flugobjekt

Feld	Typ	Beschreibung
carrierIataCode	string	Erforderlich. 2-stelliger IATA-Code, zum Beispiel LX.
airlineName	string	Anzeigename der Fluggesellschaft.
flightNumber	string	Erforderlich. Nur Ziffern, zum Beispiel 113.
originAirportCode / destinationAirportCode	string	Erforderlich. 3-stellige IATA-Codes.
originTerminal / originGate / destinationTerminal	string	Details zu Terminal und Gate.
departureDateTime	string	Erforderlich. Lokale Zeit des Abflughafens, ISO 8601 ohne Offset (zum Beispiel 2026-09-01T06:30:00).
boardingTime / arrivalDateTime	string	Gleiches lokales Format. arrivalDateTime ist die lokale Zeit am Zielort.
passengerName	string	Erforderlich.
confirmationCode / seatNumber / seatClass / boardingGroup	string	Passagierdetails.
issuerName	string	Standard ist airlineName, dann der Carrier-Code.

Transit-Objekt

Feld	Typ	Beschreibung
transitType	string	Erforderlich. BUS, RAIL, TRAM, FERRY oder OTHER.
transitOperatorName	string	Erforderlich. Erfordert logoUrl auf dem Pass.
passengerName	string	Erforderlich.
ticketNumber	string	Ticketnummer.
tripType	string	ONE_WAY (Standard) oder ROUND_TRIP.
legs	array	Eine oder mehrere Transit-Etappen in der Reihenfolge der Reise.
issuerName	string	Standard ist transitOperatorName.

Transit-Etappen-Objekt

Feld	Typ	Beschreibung
originName / destinationName	string	Erforderlich.
departureDateTime / arrivalDateTime	string	ISO 8601; Offset optional (lokale Zeit, wenn weggelassen).
platform / coach / seat	string	Einstiegsdetails.
fareName	string	Zum Beispiel Anytime Single.

Barcode-Objekt

Feld	Typ	Beschreibung
format	string	QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13 und andere Google Wallet-Barcode-Typen.
value	string	Im Barcode kodierte Daten.
altText	string	Text, der unter dem Barcode angezeigt wird.

Text-Modul-Objekt

Feld	Typ	Beschreibung
id	string	Bezeichner des Moduls.
header	string	Überschrift des Moduls.
body	string	Text des Moduls.

Link-Modul-Objekt

Feld	Typ	Beschreibung
uri	string	Externe Link-URL.
description	string	Link-Bezeichnung, die in der Detailansicht angezeigt wird.

App-Link-Objekt

Feld	Typ	Beschreibung
uri	string	Web-URL oder Deep-Link-Ziel-URI.
androidPackageName	string	Optional. Wenn festgelegt, wird die Android-App geöffnet.
description	string	Interne Beschreibung der Ziel-URI (keine sichtbare Button-Bezeichnung); Standard ist die URI.

Standort-Objekt

Feld	Typ	Beschreibung
latitude	number	-90.0 bis +90.0.
longitude	number	-180.0 bis +180.0.

Pass-Datensatz-Objekt

Wird von list/get-Endpunkten zurückgegeben.

Feld	Typ	Beschreibung
serialNumber	string	Pass-Seriennummer.
objectId	string	Vollständige Google Wallet-Objekt-ID {issuerId}.{serialNumber}.
cardTitle	string	Anzeigetitel/Überschrift für den Pass.
header	string	Sekundärer Anzeigetitel.
userId	string	Pushwoosh User-ID, für die der Pass ausgestellt wurde.
createdAt / updatedAt	string	Zeitstempel der Erstellung und der letzten Aktualisierung.
state	string	ACTIVE oder INACTIVE.
style	string	generic, offer, loyalty, eventTicket, giftCard, flight oder transit.
pass	object	Das vollständige Pass-Objekt zur Bearbeitung.