Getnet DocsGetnet Docs

Arquitectura

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Esta página explica los componentes arquitectónicos y el flujo de comunicación que impulsan la integración de Get Tap on Phone (App2App). Comprender esta arquitectura te ayuda a diseñar una integración robusta entre tu app Android, la app Tap on Phone y tus sistemas backend.

Los componentes principales

La integración App2App depende de cuatro componentes distintos que trabajan juntos para autorizar y procesar un pago de forma segura.

  1. Tu App (App Cliente) Esta es tu app Android de caja registradora electrónica (ECR) o Punto de Venta (POS). Actúa como la interfaz principal para el comerciante. Gestiona la sesión del usuario, el carrito de compra e inicia las solicitudes de pago o inicialización.
  2. App Tap on Phone (Whitelabel App) Esta es la app de pago seguro instalada en el mismo dispositivo Android. Permanece inactiva hasta que tu app la llame. Una vez invocada, toma el control de la pantalla para gestionar tareas seguras como la lectura de tarjetas NFC y la introducción del PIN, y luego devuelve el resultado a tu aplicación.
  3. Backend de Tap on Phone Esta plataforma basada en la nube enruta los datos de la transacción a las redes adquirentes y gestiona la configuración del terminal móvil. De manera crucial, intercepta las solicitudes de la app Tap on Phone y pide permiso a tu backend para proceder.
  4. Tu Backend (Client Backend) Esta es la infraestructura de servidores de tu organización. Aloja el endpoint de autorización de Single Sign-On (SSO). Valida la sesión del usuario y aprueba o deniega operaciones sensibles en función de los permisos del comerciante.

El flujo de comunicación

Dado que la app Tap on Phone opera de forma segura e independiente, depende de tu app y de tu backend para autenticar al usuario.

Esta es la secuencia de eventos cuando tu app solicita una operación protegida (como inicializar el terminal o procesar un reembolso):

  1. Inicialización: Tu app envía una solicitud a la app Tap on Phone en el dispositivo local, pasando el userId, el merchantId y un userToken seguro.
  2. Solicitud de Validación: La app Tap on Phone reenvía esta solicitud al Backend de Tap on Phone.
  3. Solicitud de Permiso de SSO: El Backend de Tap on Phone utiliza el Client ID para localizar tu endpoint de SSO específico. Envía una solicitud de API a tu backend que contiene el userToken y la operación solicitada.
  4. Autorización: Tu backend verifica el token y los permisos del usuario, devolviendo una respuesta HTTP 200 OK si se aprueba.
  5. Ejecución: El Backend de Tap on Phone indica a la app Tap on Phone que proceda con la operación.
  6. Finalización: La app Tap on Phone ejecuta la operación (por ejemplo, configurar el terminal o leer una tarjeta) y devuelve el resultado final a tu aplicación.

Patrones de comunicación de Android

Para facilitar la comunicación local entre tu app y la app Tap on Phone, la integración utiliza mecanismos estándar de Android.

Intents y la Activity Result API

Para las operaciones síncronas que requieren una interfaz de usuario —como inicializar la aplicación o procesar un pago— se utilizan Android Intents.

Para recibir el resultado de estos intents, debes utilizar las modernas Activity Result APIs (introducidas en AndroidX Activity 1.2.0 y Fragment 1.3.0).

  • Tú inicias el intent utilizando un launcher registrado.
  • La app Tap on Phone procesa la solicitud y finaliza su activity.
  • Tu callback registrado recibe un RESULT_OK (éxito) o RESULT_CANCELED (fallo o cancelación por parte del usuario), junto con un Intent que contiene los datos detallados de la respuesta (extras).

Broadcast Receivers

Para operaciones asíncronas o tareas en segundo plano que no requieren una interfaz de usuario inmediata, la integración utiliza Broadcasts.

Tú utilizas broadcasts para:

  • Comprobar el Estado del POS: Verificar si el terminal está completamente inicializado antes de intentar una transacción.
  • Activar Atestaciones: Forzar una comprobación de seguridad en segundo plano para evitar retrasos durante el flujo del proceso de pago.
  • Recuperar el Estado de la Transacción: Consultar el estado de un UUID de transacción específico si tu app falló (crashed) o perdió el Activity Result original.
  • Restablecer el POS: Borrar la sesión del usuario actual y la configuración.

Cuando envías una solicitud de broadcast a la app Tap on Phone, puedes proporcionar una cadena ResponseAction personalizada. La app Tap on Phone realiza la acción solicitada en segundo plano y emite un broadcast de respuesta utilizando exactamente esa cadena, lo que permite a tu app escuchar el resultado.