InApp Provisioning en Apps — Enrolando tarjetas
En el siguiente artículo explicaremos algunos puntos sobre como llevar a cabo el proceso de enrolamiento de una tarjeta en ApplePay, es decir, el proceso mediante el cual podremos vincular tarjetas dentro de nuestras propias apps sin tener que hacerlo a través de la aplicación Wallet incluida en nuestro dispositivo de iOS.
Flujo de In-App provisioning
Antes de empezar, explicaremos como se lleva a cabo el proceso de enrolamiento de la tarjeta desde el usuario final, hasta los servidores involucrados. Para ello veamos la siguiente figura:
- El usuario inicia el proceso de enrolamiento haciendo click en el botón de “Agregar a Apple Wallet”
2. Apple Wallet solicita los certificados públicos que deberán ser utilizados por el servidor de terceros (Issuer Host) para encriptar el payload (que nos permitirá enrolar la tarjeta).
3. Los servidores de Apple devuelven a Wallet tanto las claves públicas como un nonce/nonceSignature con el que firmar y securizar los elementos.
4. Wallet pasará a nuestra app (a través de métodos delegados) este paquete de tres elementos: claves públicas, nonce y nonceSiganture
5. Nuestra aplicación hará de puente y enviará esta información al servidor de terceros que deba ocuparse del proceso de enrolamiento.
Nota: Antes de realizar este envío es posible que la app tenga que aplicar algún cambio sobre cualquiera de los tres elementos por requerimiento del servidor, por ejemplo, pasar a base64 los nonce. No te olvides de concretar con tus proveedores como realizar este proceso :).
6. El issuer host se ocupará en este punto de:
| 6.a. Preparar el payload para el usuario
| 6.b. Generar una pareja de ephemeral key (requeridas por Apple)
| 6.c. Encriptar el payload con la clave pública enviada por Apple en los certificados públicos y generar una ephemeral key privada
| 6.d. Enviar de vuelta a la app tanto el payload (encriptado) como la ephemeral key pública. Adicionalmente, debe generar una OTP (one true pair) necesaria para el operador de pagos red (Payment Network Operator o PNO) o el proveedor de servicios y pasará también a la aplicación.
7. La app vuelve a hacer de puente entre el issuer y Apple. Se ocupa de pasar el payload [encryptedPassData], la ephemeral public key [ephemeral public key] y la OTP [activatonData] a Wallet a través de un objeto PKAddPaymentPassRequest.
8. Apple Wallet pasa estos detalles a los servidores de Apple, donde se comprueba la validez de los mismos.
9. Finalmente la información se pasa al PNO o proveedor de servicios donde se el proceso de enrolamiento concluye.
¿Por dónde comenzamos?
Ahora que ya conocemos (un poco) cómo funciona esteproceso, vamos a recopilar parte de la información que necesitamos antes de empezar a programar.
En primer lugar, debemos activar el entitlement llamado ApplePay In-App Provisioning Distribution en el developer portal del mismo modo que, por ejemplo, hacemos con las notificaciones push, app groups … vayamos pues a nuestro panel y seleccionemos Certificates, Identifiers & Profiles -> Profiles -> Nuestro perfil de distribución -> Editar -> y … ¿Dónde esta ésta configuración?
Lo primero a tener en cuenta es que este perfil no viene por defecto para ser configurado. Es necesario solicitar a Apple su activación poniéndose en contacto con ellos a través de su servicio de soporte o bien a través de e-mail
apple-pay-provisioning@apple.com.
Nota: Recuerda que las cuentas enterprise no tienen acceso a esta funcionalidad.
Una vez Apple nos haya validado como un equipo/entidad válido volveremos a visitar nuestro panel y encontraremos el siguiente menú disponible:
Como se puede ver, esta funcionalidad solo está habilitada para producción por lo que solo pueden validarse con datos reales estando en dicho entorno. Apple ofrece también soporte para realizar pruebas sobre todo de la encriptación generada por el Issuer Host (aunque no está muy documentado). Para más información podéis seguir la información contenida bajo el epígrafe “XI. Sample Payment Data” del documento “ApplePay user manual” incluido en la bibliografía.
Y ahora … ya podemos empezar a programar 🎉.
Actualización 10 de Septiembre de 2022
Revisando un proyecto en el que estuve trabajando que utiliza esta funcionalidad he encontrado que Apple requiere algunos checks adicionales para permitir a la librería PassKit funcionar y crear todos los view controllers necesarios. Estos cambios son:
- En primer lugar, hay que tocar alguna cosilla más en el developer portal. Para ello ve a developer portal -> Certificates and profiles -> Identifiers y dentro de la misma busca tu appID. Una vez dentro ve a la pestaña Additional Capabilities y, si todo esta correcto verás una opción como la indicada en la siguiente captura, opción que deberás activar.
- En segundo lugar, abre tu proyecto en Xcode y busca tu fichero de entitlements (si no lo has creado, deberás crearlo primero, sigue el enlace anterior). Una vez que estés dentro y, acorde la especificación dada por Apple, debes incluir el siguiente entitlement com.apple.developer.payment-pass-provisioning con valor YES (1) como ilustra la siguiente captura. Eso sería todo :).
Let’s coding!
Como siempre, os recomendamos leer las Review Guidelines antes de llevar a cabo la implementación para conocer las limitaciones sobre lo que podéis / no podéis hacer.
En el siguiente ejemplo nos centraremos en una implementación básica en la que agregaremos a nuestro UIViewController el botón de enrolamiento y nos ocuparemos de hacer de puente tal cual se explicó inicialmente. Dejamos en tus manos la elección de arquitectura que mejor le convenga a tu aplicación 😀.
Configuración del PassKitButton
Empecemos por lo más básico, agregando la librería de PassKit (que contiene los APIs para el manejo de InApp) y el botón de enrolamiento.
Con esto ya deberíamos ver en pantalla algo similar a:
Despliegue del proceso de enrolamiento
Ahora que ya hemos configurado nuestro botón de enrolamiento, pasemos a configurar el interfaz de Apple que se ocupa del mismo.
Vayamos por puntos:
// 1: Comprobar disponibilidad
El primer punto a tener en cuenta es si nuestro dispositivo tiene capacidad de manejar tarjetas en ApplePay. Realizamos esta comprobación y, sino, mostramos un aviso al usuario.
// 2:
Si nuestro dispositivo puede gestionar el agregado de tarjetas iniciamos la configuración del mismo.
// 3:
Precargamos la información de nuestra tarjeta con la que alimentaremos la siguiente pantalla del framework de PassKit. En este punto te deberás ocupar de recuperar la información real de tu tarjeta.
// 4 :
Pasamos a crear ahora el modelo de datos requerido. Apple permite un mínimo de configuración sobre las siguientes ventanas del flujo de enrolamiento y que podéis ver en las siguientes figuras:
Te resultarán familiares ya que son las mismas que las del flujo nativo marcado por la app Wallet.
Con el modelo de datos PKAddPaymentPassRequestConfiguration creado pasamos a crear el PKAddPaymentPassViewController que comenzará el flujo de enrolamiento reflejado en las dos figuras anteriores.
// 5:
Finalmente presentamos dicho controlador apuntándonos como delegado del mismo para escuchar los eventos reflejados por PKAddPaymentPassViewControllerDelegate.
Configuración del puente entre Apple <-> App <-> IssuerHost
Finalmente, nos tenemos que ocupar de comunicar a los interesados dentro de la aplicación como se explicó en la introducción. A través del método addPaymentPassViewController, Apple nos ofrece la información que debemos enviar a nuestro servidor (certificados, nonce y nonceSignature). En este punto debemos ponernos en contacto con nuestro servidor y enviarle esta información junto con cualquier otra necesaria para el enrolamiento (por ejemplo la numeración completa de la tarjeta). Una vez que tengamos la respuesta del mismo construiremos el objeto PKAddPaymentPassRequest mandándole de vuelta la información a Apple de una forma similar a la siguiente:
// 1:
En primer lugar prepara los datos que tu servidor necesita. Esto agrupará la información enviada por Apple más la información necesaria para la activación (por ejemplo, el pan token de tu tarjeta, la fecha de caducidad …)
// 2:
Realizamos la llamada a nuestra capa de negocio y esperamos a que termine
// 3:
Nuestro servidor debe contestarnos con la información que Apple para terminar la validación. Esto aglutina los objetos activationData, ephemeralPublicKey y encriptedPassData. Con estos construimos el objeto PKAddPaymentPassRequest y devolvemos el control a Apple a través del callback handler.
// 4:
Finalmente esperamos a la respuesta para ver si todo ha ido ok o hemos tenido algún fallo.
¡Y con esto ya tendríamos listo nuestro proceso de vinculación de tarjetas a Apple Wallet dentro de nuestra aplicación! ¡Buen trabajo! 🎉🎉
En el siguiente artículo hablaremos sobre nuevos detalles del API de PassKit que nos permitirán saber si una tarjeta está o no enrolada para personalizar la experiencia de usuario ofreciendo cambios de interfaz en función del estado de la misma 🙂.
¡Gracias por la lectura!