Skip to content
Guia da Central de Ajuda · Integrações Wallet
3 min de leituraVerificado 2026-11-16

Google Wallet

Provisionamento de classes e objetos Generic, Loyalty, Offer, Gift Card e Event via links JWT assinados.

Neste guia

Visão geral: Arquitetura em dois níveis de Classe e Objeto

Ao contrário do ficheiro binário transferível .pkpass da Apple Wallet, a Google Wallet funciona sobre um modelo de dados alojado na cloud em dois níveis, gerido através da API REST da Google Wallet (walletobjects/v1):

  1. 1
    Wallet Class (Camada de Modelo): Define a identidade visual partilhada, metadados do emissor, logótipos do programa, estrutura do layout e URLs de callback em todos os titulares de um modelo (ex.: LoyaltyClass, EventTicketClass, OfferClass, GiftCardClass, GenericClass).
  2. 2
    Wallet Object (Camada de Instância do Passe): Representa a credencial de um cliente individual referenciando a respetiva classId principal (ex.: LoyaltyObject, EventTicketObject, OfferObject, GiftCardObject, GenericObject), armazenando o código de barras único do titular, saldo de pontos, patamar e payload Smart Tap.
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CLASSE/OBJETO GOOGLE WALLET E PIPELINE SAVE JWT
ETAPA 01 FASE 1: PUBLICAR MODELOPROVISIONAMENTO DE CLASSE
Modelo Passinstance Publicado (POST/api/v1/templates/:id/publish)
Google Wallet Sync faz upsert <issuerId>.<templateClassId> via REST (LoyaltyClass | EventTicketClass | OfferClass | GiftCardClass)
ETAPA 02 FASE 2: EMISSÃO DO PASSE E GERAÇÃO SAVE JWT RS256
1
Provisiona ou incorpora <issuerId>.<passObjectId> (LoyaltyObject, etc.)
2
Assina claims JWT (iss, aud: "google", typ: "savetowallet", payload) com chave privada RSA da Conta de Serviço Google Cloud (RS256)
3
Devolve URL de Gravação: https://pay.google.com/gp/v/save/<signed_jwt>
Utilizador Guarda / Remove Passe
ETAPA 03A Google Cloud chama webhook Passinstance
POST/api/v1/wallet/callback
Evento: eventType: "save" | "del"
Atualiza telemetria instalação ativa
Alteração do Passe no Servidor
ETAPA 03B Passinstance executa REST PATCH
em walletobjects/v1/...Object
Google Play Services sincroniza cartão no Android instantaneamente

Mapeamento de programas Passinstance para Classes e Objetos Google Wallet

Os adaptadores factory da Passinstance mapeiam automaticamente a configuração do modelo para o par de recursos Google Wallet correspondente:

Programa PassinstanceRecurso Class GoogleRecurso Object GooglePrincipais campos especializados
Cartões de fidelização e carimbosLoyaltyClassLoyaltyObjectloyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier
Cupões e valesOfferClassOfferObjectredemptionChannel, provider, validTimeInterval, barcode
Cartões-presente e pré-pagosGiftCardClassGiftCardObjectcardNumber, pin, balance (micros + currencyCode), balanceUpdateTime
Bilhetes de eventosEventTicketClassEventTicketObjectseatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen
Sócios e identificaçõesGenericClassGenericObjectcardTitle, subheader, header, textModulesData, imageModulesData

Importante: Mesmo que um cliente inicie sessão com a sua Conta Google em vários dispositivos Android, a Google Wallet associa a credencial a um único <issuerId>.<objectId> canónico. A Passinstance desduplica ao nível do Objeto e contabiliza isto como 1 passe ativo Google Wallet.

Ligações Save JWT assinadas e webhooks de callback

1. Save to Google Wallet JWT assinado com RS256

Quando um titular abre uma ligação inteligente em Android, a Passinstance constrói e assina um JSON Web Token com a chave privada da sua Conta de Serviço Google Cloud e redireciona para https://pay.google.com/gp/v/save/<jwt>:

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. Callback de instalação e remoção na Google Wallet (POST /api/v1/wallet/callback)

Cada Google Wallet Class provisionada pela Passinstance define callbackOptions.url como POST /api/v1/wallet/callback. Sempre que um utilizador Android guarda um passe na Google Wallet ou o remove do dispositivo, a Google envia um payload de callback assinado:

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": Regista a instalação ativa na Google Wallet, incrementa installedDevices e dispara o gatilho de webhook/fluxo PASS_INSTALLED.
  • eventType: "del": Marca o objeto Google Wallet como desinstalado e decrementa os contadores de utilização de passes ativos.

Substituições de campos em direto para Android

Como a Google Wallet apresenta passes num layout vertical deslizável (header, cardTitle e linhas textModulesData de duas colunas) em vez do cartão fixo frente/verso da Apple Wallet, pode configurar Substituições Android no Inspetor do Editor Visual para qualquer campo ou ativo de imagem (googlePayLogo, androidBackground, androidLogo).

Saiba mais em Plataforma Google Wallet, Configuração da Google Wallet e Google Smart Tap.

Documentação de produto e API relacionada

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.