Skip to content
Guida del Centro assistenza · Certificati e credenzialiFase di onboarding 2
3 min di letturaVerificato 2026-11-16

Configurazione Google Wallet

Differenze tra Issuer ID gestito e personalizzato con override specifici per campi Google Wallet Android.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Editor Template — Tipo di pass e variante (Ingrandito)

Scegli la struttura di base (Coupon, Tessera negozio/fedeltà, Biglietto evento, Pass generico o Carta d'imbarco) e la variante.

Panoramica: configurazione Google Wallet Issuer gestita vs. personalizzata

A differenza dell'obbligo di certificato per singolo merchant richiesto da Apple Wallet, Passinstance offre fin da subito un'Infrastruttura gestita di Google Wallet Issuer, consentendo di pubblicare e distribuire pass Android immediatamente durante l'onboarding (PUT /api/v1/onboarding/wallet-setup). Per i brand enterprise che necessitano della titolarità diretta del proprio Issuer ID della Google Pay & Wallet Console o di chiavi contactless Google Smart Tap dedicate, Passinstance supporta inoltre il collegamento di un Google Cloud Service Account dedicato (POST /api/v1/google-wallet/setup).

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CONFIGURAZIONE ISSUER E SERVICE ACCOUNT GOOGLE WALLET
FASE 01 OPZIONE A: ISSUER PASSINSTANCE GESTITO (PREDEFINITO)
Nessuna configurazione Google Cloud richiesta
Attivato automaticamente durante l'onboarding (PUT/api/v1/onboarding/wallet-setup)
Passinstance firma i Save JWT e gestisce in automatico le chiamate walletobjects
FASE 02 OPZIONE B: CONFIGURAZIONE ENTERPRISE CON ISSUER DEDICATO
1
Google Pay & Wallet Console (pay.google.com/business/console)
Copi l'issuerId numerico a 19 cifre (es. 3388000000022194812)
Configuri collectorId Smart Tap (se usa il riscatto NFC contactless)
2
Google Cloud Console (console.cloud.google.com)
Abiliti "Google Wallet API" (walletobjects.googleapis.com)
Crei Service Account ed esporti chiave JSON (private_key, client_email)
3
Autorizzi il Service Account nella Google Pay & Wallet Console
Inviti client_email con ruolo Developer / Admin
4
Provisioning in Passinstance (POST/api/v1/google-wallet/setup)
Cifra il JSON del Service Account nel encrypted storage e verifica la connettività API

Prerequisiti: Quando si configura un Google Wallet Issuer ID personalizzato, è obbligatorio invitare il client_email del Google Cloud Service Account nella Google Pay & Wallet Business Console -> Users con permessi di Developer. Senza questa associazione IAM, l'API walletobjects di Google restituisce 403 Forbidden quando Passinstance tenta di creare Class o Object.

Confronto tra modalità Google Issuer gestita e personalizzata

FunzionalitàIssuer Passinstance gestitoIssuer ID Enterprise personalizzato
Tempo di configurazioneIstantaneo (0 minuti)~15 minuti (Google Cloud + Business Console)
Nome brand e logo sulla tesseraCompletamente personalizzabili per modello (issuerName, programLogo)Completamente personalizzabili per modello (issuerName, programLogo)
Accesso Google Pay & Wallet ConsoleGestito da PassinstanceAccesso diretto alla propria Google Business Console
Google Smart Tap NFC (NFC_SMART_TAP)Utilizza la configurazione workspace/lettoreSupporta i propri smartTapMerchantId e collectorId personalizzati
Webhook di callback (/api/v1/wallet/callback)Preconfigurato automaticamenteConfigurato automaticamente alla creazione della classe

API di configurazione Google Wallet e attivazione modelli (Google Wallet Setup API)

Tutti gli endpoint per l'emittente Google Wallet e il provisioning dei modelli si trovano sotto /api/v1/google-wallet:

MetodoPercorso endpointPermesso richiestoDescrizione
POST/api/v1/google-wallet/setupwallet:manage, certificates:managePredispone un account emittente Google Wallet e l'eventuale Smart Tap collector ID usando i dati aziendali del workspace.
GET/api/v1/google-wallet/statuswallet:read / wallet:manageRestituisce { isConfigured, collectorId } indicando se Google Wallet e Smart Tap sono stati predisposti.
POST/api/v1/google-wallet/repair-callbackswallet:manage, certificates:manageRisincronizza eventuali URL webhook /api/v1/wallet/callback mancanti sulle classi Google Wallet pubblicate.
POST/api/v1/google-wallet/templates/:templateId/activatewallet:manage, certificates:manageAttiva il provisioning della classe Google Wallet per uno specifico modello.
POST/api/v1/google-wallet/templates/:templateId/deactivatewallet:manage, certificates:manageDisattiva il supporto Google Wallet per uno specifico modello.
GET/api/v1/google-wallet/templates/:templateId/statuswallet:manage, certificates:readRestituisce { isEnabled, issuerId } per il modello di destinazione.

Esempio: inizializzare la configurazione Google Wallet Issuer

BASH
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>

Risposta (201 Created):

JSON
{
  "issuerId": "3388000000022194812",
  "googlePayAccount": {
    "accountIdentifier": "3388000000022194812",
    "collectorId": "50992104"
  },
  "smartTapMerchantData": {
    "smartTapMerchantId": "50992104"
  }
}

La verifica successiva tramite GET /api/v1/google-wallet/status restituisce { "isConfigured": true, "collectorId": "50992104" }, e i singoli pass espongono googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION).

Best practice durante la configurazione del modello

  1. 1
    Scegliere la categoria di pass Google corrispondente: Dentro Modifica modello -> Tipi di pass, abbini il programma a Carta fedeltà (LoyaltyClass), Offerta (OfferClass), Gift Card (GiftCardClass), Biglietto evento (EventTicketClass) o Pass generico (GenericClass) — le classi Google Wallet non possono cambiare tipo di risorsa dopo la pubblicazione.
  2. 2
    Testare esplicitamente le anteprime Android: Alterni tra Apple Wallet e Google Wallet nel pannello di anteprima live poiché rapporti d'aspetto delle immagini (androidBackground banner ampio vs ritaglio quadrato googlePayLogo) e regole di troncamento testo differiscono tra le due piattaforme.
  3. 3
    Utilizzare gli Override Android: Imposti etichette e valori dedicati per Android tramite l'Ispettore quando uno slot di layout Apple non corrisponde 1:1 su Android.

Consulti Google Wallet e Google Smart Tap per le specifiche di Class/Object e NFC.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.