Integración backend: Gestión de solicitudes de SSO

Para autorizar operaciones y gestionar el acceso de los usuarios, debes exponer un endpoint API en tu sistema backend. La plataforma Tap on Phone llama a este endpoint para verificar los permisos de Single Sign-On (SSO) siempre que tu app cliente solicite una operación sensible, como inicializar el terminal o procesar un reembolso.

Esta guía te muestra cómo implementar y configurar este endpoint para recibir, validar y responder a las solicitudes de SSO.

Paso 1: Configurar los requisitos de tu endpoint

Tu endpoint backend debe cumplir con requisitos técnicos específicos para comunicarse correctamente con la plataforma Tap on Phone:

• Protocolo: El endpoint debe utilizar HTTPS.

• Tiempo de respuesta: El endpoint debe procesar la solicitud y responder en un máximo de 5 segundos. Cualquier retraso superior provocará un timeout.

• Lista blanca de IPs: Debes configurar tu firewall o proxy inverso para permitir solicitudes entrantes desde las siguientes direcciones IP de la plataforma Tap on Phone:
  IPs del Entorno de Pruebas: * 35.156.130.116

  • 35.156.242.206

  IPs del Entorno de Producción:

  • 3.124.56.20
  • 63.176.190.170
  • 18.158.202.149
  • 18.197.125.190

Paso 2: Gestionar la solicitud entrante

Cuando un usuario activa una acción que requiere autorización (como iniciar la InitActivity), la plataforma Tap on Phone envía una solicitud POST a tu endpoint.

Cabeceras

La plataforma pasa el token de autenticación del usuario en la cabecera de la solicitud. Este token coincide con la cadena userToken que tu app cliente pasa durante la llamada del Intent.

X-Auth-Token: 1234567

Cuerpo de la Solicitud

La solicitud incluye un cuerpo JSON que detalla la operación solicitada y sus metadatos.

{
  "operation": "serviceInitialisation",
  "operationMetadata": {
    "ClientID": "4bac0922d476436697283b8238ba282b"
  }
}

• operation: El tipo de operación que el usuario intenta realizar. Los valores admitidos incluyen serviceInitialisation y refund.
• operationMetadata: Contiene metadatos contextuales, incluido el ClientID de tu organización.

Paso 3: Validar la solicitud

Al recibir la solicitud, tu backend debe realizar los siguientes pasos de validación:

1. Autenticar al usuario: Lee la cabecera X-Auth-Token y verifica que la sesión del usuario está activa y es válida dentro de tu sistema.
2. Validar el tipo de operación: Comprueba el campo operation. Determina si el usuario autenticado tiene los permisos necesarios para realizar esta acción específica (por ejemplo, asegurando que solo los usuarios administradores puedan realizar un reembolso).

Paso 4: Devolver la respuesta adecuada

Tras validar la solicitud, debes devolver una respuesta HTTP para instruir a la plataforma Tap on Phone sobre cómo proceder.

Respuesta exitosa

Si apruebas la solicitud, devuelve un estado 200 OK con un payload JSON que contenga los siguientes campos obligatorios:

• merchantId: El ID Tap to Pay (número entero) del comercio registrado en la plataforma (obtenido durante el proceso de incorporación).
• userId: El identificador único del usuario. Debe coincidir con el userId pasado originalmente por tu app cliente en el Intent.

{
  "merchantId": 19,
  "userId": "19"
}

Respuestas no exitosas

Si la solicitud no está autorizada o encuentra un error durante el procesamiento, tu backend debe devolver uno de los siguientes códigos de estado HTTP estándar:

• 401 Unauthorized: Utiliza esto si el X-Auth-Token no es válido, ha caducado o si el usuario carece de los permisos necesarios para la operación solicitada.
• 405 Method Not Allowed: Utiliza esto si el endpoint recibe un método de solicitud distinto a POST.
• 500 Internal Server Error: Utiliza esto si tu backend encuentra un problema inesperado al procesar la validación.

Próximos pasos

Una vez que tu endpoint SSO esté activo y procesando correctamente las solicitudes de autorización, estarás listo para iniciar intents desde tu aplicación Android.

Continúa en Quick Start: Your First Initialization para inicializar la sesión del POS.