Überblick: Verwaltete vs. eigene Google-Wallet-Issuer-Einrichtung
Anders als bei Apple Wallets zertifikatspflichtigem Modell pro Händler stellt Passinstance out of the box eine verwaltete Google-Wallet-Issuer-Infrastruktur bereit, sodass Sie Android-Pässe sofort ab dem Onboarding veröffentlichen und verteilen können (PUT /api/v1/onboarding/wallet-setup). Für Enterprise-Marken, die eine eigene Google Pay & Wallet Console Issuer ID oder eigene kontaktlose Google-Smart-Tap-Schlüssel führen möchten, unterstützt Passinstance zudem die Anbindung eines dedizierten Google-Cloud-Dienstkontos (POST /api/v1/google-wallet/setup).
Voraussetzungen: Wenn Sie eine eigene Google Wallet Issuer ID konfigurieren, müssen Sie die
client_emailIhres Google-Cloud-Dienstkontos in der Google Pay & Wallet Business Console -> Benutzer mit der Rolle Developer einladen. Ohne diese IAM-Verknüpfung liefert Googleswalletobjects-API den Fehler403 Forbidden, sobald Passinstance Classes oder Objects anlegen möchte.
Vergleich: Verwalteter vs. eigener Google-Issuer-Modus
| Funktion | Verwalteter Passinstance-Issuer | Eigene Enterprise Issuer ID |
|---|---|---|
| Einrichtungszeit | Sofort (0 Minuten) | Ca. 15 Minuten (Google Cloud + Business Console) |
| Markenname & Logo auf der Karte | Pro Vorlage frei anpassbar (issuerName, programLogo) | Pro Vorlage frei anpassbar (issuerName, programLogo) |
| Zugriff auf Google Pay & Wallet Console | Von Passinstance verwaltet | Direkter Zugriff auf Ihre eigene Google Business Console |
Google Smart Tap NFC (NFC_SMART_TAP) | Nutzt Workspace-/Reader-Konfiguration | Unterstützt Ihre eigene smartTapMerchantId & collectorId |
Callback-Webhook (/api/v1/wallet/callback) | Automatisch vorkonfiguriert | Bei Klassenerstellung automatisch konfiguriert |
Google-Wallet-Einrichtungs- & Vorlagen-Aktivierungs-API (Google Wallet Setup API)
Alle Endpunkte zur Google-Wallet-Issuer- und Vorlagenbereitstellung befinden sich unter /api/v1/google-wallet:
| Methode | Endpunkt-Pfad | Erforderliche Berechtigung | Beschreibung |
|---|---|---|---|
| POST | /api/v1/google-wallet/setup | wallet:manage, certificates:manage | Richtet ein Google-Wallet-Issuer-Konto und optional eine Smart-Tap-Collector-ID anhand Ihrer Workspace-Firmendaten ein. |
| GET | /api/v1/google-wallet/status | wallet:read / wallet:manage | Liefert { isConfigured, collectorId } und zeigt an, ob Google Wallet und Smart Tap eingerichtet sind. |
| POST | /api/v1/google-wallet/repair-callbacks | wallet:manage, certificates:manage | Synchronisiert fehlende /api/v1/wallet/callback-Webhook-URLs auf veröffentlichten Google-Wallet-Klassen neu. |
| POST | /api/v1/google-wallet/templates/:templateId/activate | wallet:manage, certificates:manage | Aktiviert die Google-Wallet-Klassenbereitstellung für eine bestimmte Vorlage. |
| POST | /api/v1/google-wallet/templates/:templateId/deactivate | wallet:manage, certificates:manage | Deaktiviert die Google-Wallet-Unterstützung für eine bestimmte Vorlage. |
| GET | /api/v1/google-wallet/templates/:templateId/status | wallet:manage, certificates:read | Gibt { isEnabled, issuerId } für die Zielvorlage zurück. |
Beispiel: Einrichtung des Google-Wallet-Issuers anstoßen
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>
Antwort (201 Created):
{
"issuerId": "3388000000022194812",
"googlePayAccount": {
"accountIdentifier": "3388000000022194812",
"collectorId": "50992104"
},
"smartTapMerchantData": {
"smartTapMerchantId": "50992104"
}
}
Eine anschließende Statusabfrage über GET /api/v1/google-wallet/status liefert { "isConfigured": true, "collectorId": "50992104" }, und einzelne Pässe weisen das Feld googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION) aus.
Best Practices bei der Vorlageneinrichtung
-
1
Passende Google-Pass-Kategorie wählen: Ordnen Sie Ihr Programm unter Vorlage bearbeiten -> Pass-Typen passend zu Loyalty (
LoyaltyClass), Offer (OfferClass), Geschenkkarte (GiftCardClass), Event-Ticket (EventTicketClass) oder Generischer Pass (GenericClass) zu — Google-Wallet-Klassen können ihren Ressourcentyp nach der Veröffentlichung nicht mehr ändern. -
2
Android-Vorschau gezielt testen: Wechseln Sie im Live-Vorschaupanel zwischen Apple Wallet und Google Wallet, da sich Bildseitenverhältnisse (breites Hero-Banner
androidBackgroundvs. quadratischer ZuschnittgooglePayLogo) und Feldkürzungsregeln zwischen den Plattformen unterscheiden. -
3
Android Overrides nutzen: Hinterlegen Sie im Inspektor angepasste Android-Feldbeschriftungen und -Werte, wenn ein Apple-Layout-Slot unter Android nicht 1:1 abgebildet wird.
Weitere Informationen zu Klassen/Objekten und NFC-Spezifikationen finden Sie unter Google Wallet und Google Smart Tap.
