Skip to content
Guia da Central de Ajuda · Certificados e credenciaisFase de integração 2
4 min de leituraVerificado 2026-11-16

Configuração do Google Wallet

Compreenda o Issuer ID gerido versus próprio no Google Wallet e personalizações específicas para Android.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Editor — Tipo de passe e layout (Ampliado)

Escolha a estrutura (Cupom, Cartão Loja/Fidelidade, Ingresso, Genérico ou Embarque) e a variante visual.

Visão Geral: Configuração Gerida vs. Personalizada de Emissor Google Wallet

Ao contrário do requisito de certificado por comerciante da Apple Wallet, a Passinstance fornece uma Infraestrutura Gerida de Emissor da Google Wallet pronta a usar para que possa publicar e distribuir passes Android imediatamente durante o onboarding (PUT /api/v1/onboarding/wallet-setup). Para marcas empresariais que necessitam da propriedade do seu próprio Issuer ID da Google Pay & Wallet Console ou de chaves sem contacto Google Smart Tap personalizadas, a Passinstance também suporta a associação de uma Conta de Serviço do Google Cloud dedicada (POST /api/v1/google-wallet/setup).

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: EMISSOR E CONTA DE SERVIÇO GOOGLE WALLET
ETAPA 01 OPÇÃO A: EMISSOR GERIDO PASSINSTANCE (PREDEFINIÇÃO)
Zero configuração necessária no Google Cloud
Ativado automaticamente no Onboarding (PUT/api/v1/onboarding/wallet-setup)
A Passinstance assina Save JWTs e gere chamadas REST walletobjects
ETAPA 02 OPÇÃO B: CONFIGURAÇÃO DE EMISSOR EMPRESARIAL PERSONALIZADO
1
Google Pay & Wallet Console (pay.google.com/business/console)
Copie o issuerId numérico de 19 dígitos (ex.: 3388000000022194812)
Configure o collectorId do Smart Tap (se usar resgate NFC sem contacto)
2
Google Cloud Console (console.cloud.google.com)
Ative a "Google Wallet API" (walletobjects.googleapis.com)
Crie uma Conta de Serviço e exporte a chave JSON (private_key, client_email)
3
Autorize a Conta de Serviço na Google Pay & Wallet Console
Convide client_email com acesso Developer / Admin
4
Aprovisione na Passinstance (POST/api/v1/google-wallet/setup)
Encripta o JSON da Conta de Serviço no encrypted storage e valida a ligação à API

Pré-requisitos: Ao configurar um Issuer ID personalizado da Google Wallet, tem de convidar o client_email da Conta de Serviço do Google Cloud na Google Pay & Wallet Business Console -> Utilizadores com permissões de Developer. Sem esta vinculação IAM, a API walletobjects da Google devolve 403 Forbidden quando a Passinstance tenta criar Classes ou Objetos.

Comparação entre Modo de Emissor Google Gerido vs. Personalizado

CapacidadeEmissor Gerido PassinstanceIssuer ID Empresarial Personalizado
Tempo de ConfiguraçãoInstantâneo (0 minutos)~15 minutos (Google Cloud + Business Console)
Nome da Marca e Logótipo no CartãoTotalmente personalizado por modelo (issuerName, programLogo)Totalmente personalizado por modelo (issuerName, programLogo)
Acesso à Google Pay & Wallet ConsoleGerido pela PassinstanceAcesso direto à sua própria Google Business Console
Google Smart Tap NFC (NFC_SMART_TAP)Utiliza a configuração do espaço de trabalho/leitorSuporta o seu próprio smartTapMerchantId e collectorId personalizados
Webhook de Retorno (/api/v1/wallet/callback)Pré-configurado automaticamenteConfigurado automaticamente na criação da classe

API de Configuração da Google Wallet e Ativação de Modelos (Google Wallet Setup API)

Todos os endpoints de aprovisionamento de emissores e modelos da Google Wallet encontram-se sob /api/v1/google-wallet:

MétodoCaminho do EndpointPermissão NecessáriaDescrição
POST/api/v1/google-wallet/setupwallet:manage, certificates:manageAprovisiona uma conta de emissor Google Wallet e um collector ID Smart Tap opcional utilizando os dados da empresa do seu espaço de trabalho.
GET/api/v1/google-wallet/statuswallet:read / wallet:manageDevolve { isConfigured, collectorId } indicando se a Google Wallet e o Smart Tap estão aprovisionados.
POST/api/v1/google-wallet/repair-callbackswallet:manage, certificates:manageResincroniza URLs de webhook /api/v1/wallet/callback em falta nas Classes Google Wallet publicadas.
POST/api/v1/google-wallet/templates/:templateId/activatewallet:manage, certificates:manageAtiva o aprovisionamento de classes Google Wallet para um modelo específico.
POST/api/v1/google-wallet/templates/:templateId/deactivatewallet:manage, certificates:manageDesativa o suporte Google Wallet para um modelo específico.
GET/api/v1/google-wallet/templates/:templateId/statuswallet:manage, certificates:readDevolve { isEnabled, issuerId } para o modelo de destino.

Exemplo: Inicializar a Configuração do Emissor Google Wallet

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

Resposta (201 Created):

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

A verificação posterior do estado através de GET /api/v1/google-wallet/status devolve { "isConfigured": true, "collectorId": "50992104" }, e os passes individuais expõem googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION).

Boas Práticas Durante a Configuração de Modelos

  1. 1
    Escolha a Categoria de Passe Google Correspondente: Em Editar Modelo -> Tipos de Passe, faça corresponder o seu programa a Fidelização (LoyaltyClass), Oferta (OfferClass), Cartão Presente (GiftCardClass), Bilhete de Evento (EventTicketClass) ou Passe Genérico (GenericClass) — as classes da Google Wallet não podem mudar o tipo de recurso após serem publicadas.
  2. 2
    Teste Explicitamente as Pré-visualizações Android: Alterne entre Apple Wallet e Google Wallet no painel de pré-visualização em tempo real, pois as proporções de imagem (banner principal largo androidBackground vs. recorte quadrado googlePayLogo) e as regras de truncagem de campos diferem entre plataformas.
  3. 3
    Utilize Substituições Android: Defina etiquetas e valores de campos Android adaptados através do Inspetor quando uma posição do layout Apple não tiver correspondência 1:1 no Android.

Consulte Google Wallet e Google Smart Tap para especificações de classes/objetos e NFC.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.