Descripción general: configuración administrada frente a emisor personalizado de Google Wallet
A diferencia del requisito de certificado por comercio de Apple Wallet, Passinstance incluye de serie una Infraestructura administrada de emisor de Google Wallet para que pueda publicar y distribuir pases en Android inmediatamente durante la incorporación (PUT /api/v1/onboarding/wallet-setup). Para marcas empresariales que necesitan titularidad sobre su propio Issuer ID en Google Pay & Wallet Console o claves personalizadas sin contacto de Google Smart Tap, Passinstance también admite vincular una cuenta de servicio dedicada de Google Cloud (POST /api/v1/google-wallet/setup).
Requisitos previos: Al configurar un Google Wallet Issuer ID personalizado, debe invitar al correo
client_emailde la cuenta de servicio de Google Cloud dentro de Google Pay & Wallet Business Console -> Users con permisos de Developer. Sin este vínculo IAM, la APIwalletobjectsde Google devolverá403 Forbiddencuando Passinstance intente crear Clases u Objetos.
Comparativa entre el modo de emisor administrado y personalizado
| Capacidad | Emisor administrado por Passinstance | Issuer ID empresarial personalizado |
|---|---|---|
| Tiempo de configuración | Instantáneo (0 minutos) | ~15 minutos (Google Cloud + Business Console) |
| Nombre de marca y logotipo en tarjeta | Totalmente personalizado por plantilla (issuerName, programLogo) | Totalmente personalizado por plantilla (issuerName, programLogo) |
| Acceso a Google Pay & Wallet Console | Administrado por Passinstance | Acceso directo a su propia Google Business Console |
Google Smart Tap NFC (NFC_SMART_TAP) | Utiliza la configuración de espacio de trabajo y lector | Admite su propio smartTapMerchantId y collectorId personalizados |
Webhook de callback (/api/v1/wallet/callback) | Preconfigurado automáticamente | Configurado automáticamente al crear la clase |
API de configuración y activación de plantillas de Google Wallet (Google Wallet Setup API)
Todos los endpoints de aprovisionamiento de emisores y plantillas de Google Wallet residen bajo /api/v1/google-wallet:
| Método | Ruta del endpoint | Permiso requerido | Descripción |
|---|---|---|---|
| POST | /api/v1/google-wallet/setup | wallet:manage, certificates:manage | Aprovisiona una cuenta emisora de Google Wallet y un ID de colector Smart Tap opcional utilizando los datos de empresa del espacio de trabajo. |
| GET | /api/v1/google-wallet/status | wallet:read / wallet:manage | Devuelve { isConfigured, collectorId } indicando si Google Wallet y Smart Tap están aprovisionados. |
| POST | /api/v1/google-wallet/repair-callbacks | wallet:manage, certificates:manage | Resincroniza las URL de webhook /api/v1/wallet/callback faltantes en las clases publicadas de Google Wallet. |
| POST | /api/v1/google-wallet/templates/:templateId/activate | wallet:manage, certificates:manage | Activa el aprovisionamiento de clases de Google Wallet para una plantilla específica. |
| POST | /api/v1/google-wallet/templates/:templateId/deactivate | wallet:manage, certificates:manage | Desactiva la compatibilidad con Google Wallet para una plantilla específica. |
| GET | /api/v1/google-wallet/templates/:templateId/status | wallet:manage, certificates:read | Devuelve { isEnabled, issuerId } para la plantilla de destino. |
Ejemplo: inicializar la configuración del emisor de Google Wallet
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>
Respuesta (201 Created):
{
"issuerId": "3388000000022194812",
"googlePayAccount": {
"accountIdentifier": "3388000000022194812",
"collectorId": "50992104"
},
"smartTapMerchantData": {
"smartTapMerchantId": "50992104"
}
}
Consultar después el estado mediante GET /api/v1/google-wallet/status devuelve { "isConfigured": true, "collectorId": "50992104" }, y los pases individuales exponen googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION).
Buenas prácticas durante la configuración de plantillas
-
1
Elegir la categoría coincidente en Google Wallet: Dentro de Editar plantilla -> Tipos de pase, haga coincidir su programa con Fidelización (
LoyaltyClass), Oferta (OfferClass), Tarjeta regalo (GiftCardClass), Entrada de evento (EventTicketClass) o Pase genérico (GenericClass): las clases de Google Wallet no pueden cambiar de tipo de recurso una vez publicadas. -
2
Probar explícitamente la vista previa de Android: Alterne entre Apple Wallet y Google Wallet en el panel de vista previa en vivo, ya que las proporciones de imagen (banner ancho
androidBackgroundfrente al recorte cuadradogooglePayLogo) y las reglas de truncado de campos difieren entre ambas plataformas. -
3
Usar anulaciones para Android: Defina etiquetas y valores específicos para Android desde el Inspector cuando una ranura de diseño de Apple no tenga correspondencia 1:1 en Android.
Consulte Google Wallet y Google Smart Tap para especificaciones de clases, objetos y NFC.
