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
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
Wallet Object (Capa de instancia de pase): Representa la credencial individual de un cliente referenciando a su
classIdmatriz (por ejemplo,LoyaltyObject,EventTicketObject,OfferObject,GiftCardObject,GenericObject), conteniendo su código de barras único, saldo de puntos, nivel y payload de Smart Tap.
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 Passinstance | Recurso Google Class | Recurso Google Object | Campos especializados principales |
|---|---|---|---|
| Tarjetas de fidelidad y sellos | LoyaltyClass | LoyaltyObject | loyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier |
| Cupones y vales | OfferClass | OfferObject | redemptionChannel, provider, validTimeInterval, barcode |
| Tarjetas regalo y prepago | GiftCardClass | GiftCardObject | cardNumber, pin, balance (micros + currencyCode), balanceUpdateTime |
| Entradas de eventos | EventTicketClass | EventTicketObject | seatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen |
| Membresías e identificaciones | GenericClass | GenericObject | cardTitle, 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>:
{
"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:
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, incrementainstalledDevicesy dispara el activador de webhook o flujo de trabajoPASS_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.
