Migración Push Provisioning a UPP

Cómo implementar los cambios necesarios para migrar a la API Unified Android Push Provisioning (UPP).

Por qué migrar

Google actualizó el flujo de Android Push Provisioning para soportar la API Unified Android Push Provisioning (UPP). Esta versión unifica dentro del mismo flujo la tokenización de la tarjeta con el TSP y el guardado de la FPAN en Google Wallet.

Con UPP, además del TSP OPC, Google necesita recibir un Google OPC para guardar la FPAN en Google Wallet. Esto te permite:

• Agregar la tarjeta una vez y que quede disponible en todos los productos de Google compatibles.
• Ofrecer una experiencia consistente entre la tokenización manual iniciada en Google Wallet y el flujo de Push Provisioning iniciado desde tu app.

Por este motivo, después de migrar a UPP, el botón "Agregar a Billetera de Google" de tu app Android tiene que compartir ambos valores en todos los casos:

• El TSP OPC, para tokenizar la tarjeta y generar el DPAN.
• El Google OPC, para que Google guarde la FPAN en Google Wallet.

La migración actualiza dos partes del flujo:

1. En el servidor: reemplazar los endpoints deprecados de Push Provisioning por sus equivalentes UPP.
2. En la app mobile: actualizar cómo construyes PushTokenizeRequest, cómo generas las credenciales y cómo manejas el resultado de pushTokenize.

Cómo cambia el flujo

El ajuste principal está en cómo tu app obtiene y comparte las credenciales necesarias durante el flujo de Push Provisioning. Además, junto con la migración tienes que integrar Bounce Provisioning, que sí suma requisitos de experiencia de usuario.

Con la integración deprecada, tu app obtiene el TSP OPC antes de construir PushTokenizeRequest y luego ejecuta pushTokenize.

Con UPP, la generación de credenciales ocurre durante la ejecución de pushTokenize. Para eso, tienes que configurar una implementación de PaymentCredentialsGenerator. El SDK de Tap And Pay invoca esa implementación y entrega los datos necesarios para completar el request contra Pomelo, incluyendo server_session_id.

Durante pushTokenize, el SDK de Tap And Pay le pide las credenciales a tu app. En ese momento, tu app obtiene desde Pomelo el TSP OPC y el Google OPC, y devuelve ambos valores al SDK para continuar el flujo.

Vinculación de llaves PGP

Para garantizar la transmisión segura del FPAN del usuario a Google en el Google OPC, es necesario intercambiar llaves PGP con Google. Este proceso ya lo completamos nosotros; solo tienes que informar a Google que seremos tu Program Manager completando el siguiente formulario.

Ingresa al formulario de onboarding y completa los siguientes campos:

• Type of request: selecciona Aggregator/Program Manager linking.
• Merchant ID of Aggregator: ingresa el valor BCR2DN4T27N27OKJ.

Una vez que envíes el formulario, Google puede tardar hasta 5 días hábiles de Estados Unidos en confirmar la vinculación.

Para verificar que la vinculación fue exitosa, ingresa a la sección Claves de Issuer Console. Si el proceso se completó, verás un banner como este:

Cambios en el servidor

Tienes que reemplazar los endpoints deprecados por sus equivalentes UPP.

Los endpoints UPP mantienen una estructura similar a los deprecados, pero incorporan dos cambios principales:

1. Tienes que enviar server_session_id en el body del request.
2. Tienes que contemplar google_opc en la respuesta, además del TSP OPC para tokenización.

Tu servidor tiene que recibir server_session_id desde la app mobile, enviarlo al endpoint UPP correspondiente para Visa o Mastercard, y devolver google_opc para que la app pueda completar la respuesta de PaymentCredentialsGenerator.

Cambios en la app mobile

PushTokenize

Los cambios se concentran alrededor de pushTokenize.

Con la integración deprecada, el flujo es el siguiente:

1. Ir a buscar el TSP OPC contra Pomelo.
2. Construir PushTokenizeRequest.
3. Ejecutar pushTokenize de Tap And Pay.

Con UPP, ese orden cambia:

1. Construyes PushTokenizeRequest.
2. Configuras una implementación de PaymentCredentialsGenerator.
3. Ejecutas pushTokenize.
4. El SDK de Tap And Pay invoca PaymentCredentialsGenerator.
5. Tu app llama a nuestro endpoint UPP usando server_session_id.
6. Tu app construye GeneratePaymentCredentialsResponse con opc y google_opc.

PaymentCredentialsGenerator

PaymentCredentialsGenerator es el punto donde tu app genera las credenciales que necesita el SDK de Tap And Pay durante pushTokenize.

En la implementación migrada, el método generate(...) recibe un GeneratePaymentCredentialsRequest con datos provistos por Google:

• serverSessionId
• stableHardwareId
• walletId

Usa estos valores para llamar a tu servidor, que a su vez llama al endpoint UPP de Pomelo. Con la respuesta, construye GeneratePaymentCredentialsResponse y asigna:

• opc con setOpaquePaymentCard(...)
• google_opc con setGoogleOpaquePaymentCard(...)

Manejo del resultado de pushTokenize

Te recomendamos actualizar el manejo del resultado de pushTokenize usando PushTokenizeResult del SDK de Tap And Pay para centralizar en un mismo lugar la resolución de estos escenarios:

• Tokenización exitosa
• Flujo cancelado por el tarjetahabiente
• Tokenización con error

Este enfoque, alineado con el ejemplo oficial de pushTokenize(...), evita distribuir la lógica de resultado en múltiples puntos de tu app y te facilita mapear la respuesta del SDK a un estado propio de tu integración, como PushProvisioningResult.

Bounce Provisioning

Integrar Bounce Provisioning es un requisito para lanzar con UPP.

Cuando tu cliente quiere agregar una tarjeta a Google Wallet, no siempre empieza por tu app. Muchas veces abre Google Wallet directamente y busca su banco o fintech desde ahí. Sin Bounce Provisioning, ese cliente tiene que salir de Google Wallet, abrir tu app por su cuenta y volver a empezar.

Con Bounce Provisioning, Google Wallet muestra tu app en el listado de emisores disponibles y, cuando tu cliente la elige, la abre directo en la pantalla para agregar la tarjeta. El flujo de tokenización sigue siendo el tuyo, con tu marca y tus controles de seguridad: lo que cambia es el punto de entrada.

Encuentras el paso a paso de la integración, los requisitos de experiencia de usuario y la habilitación de tu package name con Google en la guía de Bounce Provisioning, dentro de la sección de Capacitaciones del Dashboard.

Guía: Bounce Provisioning

Ejemplos técnicos

Aquí te compartimos ejemplos de referencia para visualizar los cambios principales. Ajústalos según la arquitectura y las clases de tu app.

Implementación deprecada alrededor de pushTokenize

Implementación migrada a UPP

Manejo del resultado de pushTokenize

Repositorio de ejemplo

Para complementar esta guía, te compartimos un repositorio de ejemplo con una implementación de punta a punta de UPP.

El repositorio incluye:

• Una app mobile Android que integra el SDK de Tap And Pay.
• Un backend de ejemplo que expone los endpoints consumidos por la app.
• El flujo de PaymentCredentialsGenerator.
• El manejo del resultado de pushTokenize.

Puedes usarlo como referencia para entender cómo se conectan los cambios de servidor y app mobile dentro de una misma integración.

Repositorio: example-android-app-google-upp

Pruebas de campo

Este paso tiene por objetivo verificar que tu aplicación y tus tokens funcionen bien en producción, antes de lanzar la función públicamente.

Para completar este paso deberás cumplir estos requisitos:

1. Genera al menos 10 tokens push provisioned en producción en los últimos 30 días, con una tasa de éxito mayor al 90%. Puede haber hasta 24 horas de demora entre la creación de los tokens y su verificación por parte de Google.
   • El FPAN debe guardarse con cada tokenización exitosa. Puedes verificarlo ingresando a wallet.google.com y navegando a la página de Métodos de pago. Te recomendamos realizar una compra en Play Store desde una computadora con la misma cuenta de Google en la que fue aprovisionada la tarjeta.
   • Al menos 10 tokens deben provisionarse exitosamente a través del flujo de Bounce Provisioning, con una tasa de éxito mayor al 90%.
2. Realiza al menos 3 transacciones con tokens push provisioned en producción, con una tasa de éxito mayor al 90%. No hay un monto mínimo.
   • Al menos una tarjeta debe estar disponible para transacciones online con un FPAN guardado mediante esta API.
   • Al menos 3 transacciones deben usar específicamente tokens agregados a través de Bounce Provisioning, con una tasa de éxito mayor al 90%.
3. Genera al menos 5 tokens exitosamente en un dispositivo wearable en producción, con una tasa de éxito de tokenización mayor al 90%.
4. Realiza al menos 1 transacción exitosa usando una tarjeta tokenizada en un dispositivo wearable.
5. Las pruebas de campo deben cubrir los siguientes casos de uso:
   • El usuario es el propietario principal de la cuenta de la tarjeta.
   • El usuario tiene una o más tarjetas del mismo emisor.
   • El usuario es co-deudor de una tarjeta (si corresponde).
   • El usuario es el usuario autorizado de la tarjeta (si corresponde).
6. Cumple con los siguientes requisitos de UX de Bounce Provisioning:
   • Tu app tiene que aparecer en la pantalla "Agregar tarjeta de pago" de Google Wallet.
   • Tu app tiene que mostrar el botón "Add to Google Wallet" correspondiente, con la tarjeta disponible para tokenizar.

Una vez que hayas cumplido con estos requisitos, puedes solicitar la aprobación final directamente desde Issuer Console, sin necesidad de completar ningún formulario adicional. La consola también te brinda visibilidad sobre los TSPs y flujos de UX aprobados para lanzar con tu app.