Skip to content
Guía del Centro de ayuda · Integraciones Wallet
3 min de lecturaVerificado 2026-11-16

Google Wallet

Provisión de clases y objetos Generic, Loyalty, Offer, Gift Card y Event mediante enlaces JWT firmados.

En esta guía

Descripción general: arquitectura en dos niveles de Class y Object

A diferencia del archivo binario descargable .pkpass de Apple Wallet, Google Wallet funciona sobre un modelo de datos en dos niveles alojado en la nube y gestionado mediante la API REST de Google Wallet (walletobjects/v1):

  1. 1
    Wallet Class (Capa de plantilla): Define la identidad visual compartida, metadatos del emisor, logotipos del programa, estructura de diseño y URL de callback comunes a todos los titulares de una plantilla (por ejemplo, LoyaltyClass, EventTicketClass, OfferClass, GiftCardClass, GenericClass).
  2. 2
    Wallet Object (Capa de instancia de pase): Representa la credencial individual de un cliente referenciando a su classId matriz (por ejemplo, LoyaltyObject, EventTicketObject, OfferObject, GiftCardObject, GenericObject), conteniendo su código de barras único, saldo de puntos, nivel y payload de Smart Tap.
FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CLASE/OBJETO GOOGLE WALLET Y TUBERÍA SAVE JWT
ETAPA 01 FASE 1: PUBLICACIÓN DE PLANTILLAAPROVISIONAMIENTO DE CLASS
Plantilla Passinstance publicada (POST/api/v1/templates/:id/publish)
Google Wallet Sync hace upsert de <issuerId>.<templateClassId> vía REST (LoyaltyClass | EventTicketClass | OfferClass | GiftCardClass)
ETAPA 02 FASE 2: EMISIÓN DE PASE Y GENERACIÓN DE SAVE JWT RS256
1
Aprovisionar o incrustar <issuerId>.<passObjectId> (LoyaltyObject, etc.)
2
Firmar claims JWT (iss, aud: "google", typ: "savetowallet", payload) usando la clave privada RSA de Google Cloud Service Account (RS256)
3
Devolver URL Save: https://pay.google.com/gp/v/save/<signed_jwt>
El usuario guarda / elimina
ETAPA 03A Google Cloud invoca el webhook de
Passinstance:`POST/api/v1/wallet/callbac
Evento: eventType: "save" | "del"
Actualiza telemetría de instalación
Mutación del pase en servidor
ETAPA 03B Passinstance ejecuta PATCH REST
sobre walletobjects/v1/...Object
Google Play Services sincroniza la tarjeta Android al instante

Mapeo de programas de Passinstance a Clases y Objetos de Google Wallet

Los adaptadores de fábrica de Passinstance asignan automáticamente la configuración de su plantilla al par de recursos correspondiente en Google Wallet:

Programa PassinstanceRecurso Google ClassRecurso Google ObjectCampos especializados principales
Tarjetas de fidelidad y sellosLoyaltyClassLoyaltyObjectloyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier
Cupones y valesOfferClassOfferObjectredemptionChannel, provider, validTimeInterval, barcode
Tarjetas regalo y prepagoGiftCardClassGiftCardObjectcardNumber, pin, balance (micros + currencyCode), balanceUpdateTime
Entradas de eventosEventTicketClassEventTicketObjectseatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen
Membresías e identificacionesGenericClassGenericObjectcardTitle, subheader, header, textModulesData, imageModulesData

Importante: Incluso si un cliente inicia sesión con su cuenta de Google en varios dispositivos Android, Google Wallet vincula la credencial a un único objeto canónico <issuerId>.<objectId>. Passinstance deduplica a nivel de Objeto y contabiliza esto como 1 pase activo de Google Wallet.

Enlaces Save JWT firmados y webhooks de callback

1. Save to Google Wallet JWT firmado con RS256

Cuando un titular abre un enlace inteligente en Android, Passinstance construye y firma un JSON Web Token con la clave privada de su Google Cloud Service Account y redirige a 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 instalación y eliminación de Google Wallet (POST /api/v1/wallet/callback)

Cada Google Wallet Class aprovisionada por Passinstance establece callbackOptions.url en POST /api/v1/wallet/callback. Siempre que un usuario Android guarda o elimina un pase de su Google Wallet, Google envía un payload firmado de callback:

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": Registra la instalación activa en Google Wallet, incrementa installedDevices y dispara el activador de webhook o flujo de trabajo PASS_INSTALLED.
  • eventType: "del": Marca el objeto de Google Wallet como desinstalado y decrementa los contadores de uso activo de pases.

Anulaciones de campos en vivo para Android

Dado que Google Wallet presenta los pases con una tarjeta de desplazamiento vertical (header, cardTitle y filas de dos columnas textModulesData) en lugar de la tarjeta reversible fija de Apple Wallet, puede configurar Anulaciones para Android en el Inspector del editor visual para cualquier campo o recurso de imagen (googlePayLogo, androidBackground, androidLogo).

Aprenda más en Plataforma Google Wallet, Configuración de Google Wallet y Google Smart Tap.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.