Ciclo de vida de la transacción

Una transacción de pago en el Get Mini Android SDK se ejecuta a través de una secuencia coordinada de operaciones entre tu aplicación Android, la biblioteca mPOS integrada, el PIN pad externo de Get Mini y el servidor de autorización. Comprender este ciclo de vida es esencial para la gestión correcta de sesiones, la retroalimentación del usuario y el manejo seguro de situaciones excepcionales.

Este documento describe el flujo de transacción tal como está implementado por el Get Mini Android SDK, basado en llamadas de método directas y objetos de respuesta síncronos.

Comprender las etapas de la transacción

Cada transacción con tarjeta presente progresa a través de cuatro etapas lógicas. Estas etapas reflejan las responsabilidades reales definidas en el Get Mini Android SDK y el protocolo del PIN pad.

En cada etapa, pueden ocurrir fallos que requieren un manejo explícito por parte de la aplicación.

Etapa 1: Inicialización y conexión del PIN pad

Antes de que se pueda realizar cualquier operación de pago, la aplicación debe asegurarse de que:

• El entorno de ejecución (integración, certificación o producción) esté configurado a través de RedCLSConfigurationLibrary.setiEntorno().
• La licencia de la aplicación se haya inicializado a través de RedCLSConfigurationLibrary.setAppLicense().
• Se haya realizado un inicio de sesión exitoso (con credenciales a través de RedCLSMerchantConfigurationManager.login() o inicio de sesión transparente a través de autoLogin()/loginWithoutUser()).
• Se haya seleccionado un terminal válido (RedCLSTerminalData) de la respuesta de inicio de sesión.

Una vez que se satisfacen estos requisitos previos, la aplicación debe establecer una conexión con el PIN pad usando el RedCLSPinPadManager. El PIN pad se puede conectar a través de Bluetooth, USB o Wi-Fi, dependiendo de la configuración de RedCLSConfigurationPinPadData.

El proceso de conexión implica:

1. Instanciar RedCLSPinPadManager con un delegado que implemente RedCLSPinPadInterface, la configuración del PIN pad y los datos del terminal.
2. Llamar a connectWithPinPad() para establecer la conexión física.
3. Esperar la devolución de llamada conexionPinPadRealizada() para confirmar la conexión exitosa.

Después de que se establece la conexión física, el PIN pad debe ser inicializado explícitamente llamando a inicializarPinpad(). Durante este proceso, el SDK:

• Verifica que el PIN pad esté autorizado para el terminal seleccionado.
• Sincroniza la configuración y los parámetros.
• Realiza de forma transparente la carga de claves o actualizaciones de software si es necesario (telecarga).

La inicialización devuelve un objeto RedCLSInitPinPadResponse que contiene el estado, la información del terminal y los detalles de carga de claves.

La inicialización típicamente ocurre una vez por sesión de aplicación. Las transacciones posteriores pueden reutilizar la conexión existente y el estado de inicialización a menos que se pierda la conexión o se reinicie el PIN pad.

Etapa 2: Lectura de tarjeta e interacción con el cliente

Una vez que los parámetros de la transacción (importe, referencia de factura y banderas opcionales) se construyen en un objeto RedCLSOperativeWithCardData, la aplicación invoca la operación de pago:

RedCLSOperativeWithCardResponse response =
    pinPadManager.operativaConTarjeta(operativeData);

En este punto, el PIN pad entra en un estado interactivo y solicita la entrada del cliente. Dependiendo de la tarjeta y el contexto de la transacción, esto puede involucrar:

• Contactless: tocar una tarjeta o dispositivo móvil en el lector NFC del PIN pad.
• Chip (EMV): insertar la tarjeta en el lector y, si es necesario, ingresar el PIN en el teclado seguro.
• Banda: deslizar la tarjeta a través del lector.

Toda la captura de datos de la tarjeta, entrada de PIN y procesamiento criptográfico se realizan exclusivamente en el PIN pad. La aplicación Android nunca tiene acceso a los datos sin procesar de la tarjeta.

Durante esta etapa, la aplicación puede recibir devoluciones de llamada a través de RedCLSPinPadInterface para:

• DCC (Dynamic Currency Conversion): La devolución de llamada seleccionMonedaPagoDCC() permite al cliente elegir la moneda de la transacción.
• Aplazamiento del pago (Installments): La devolución de llamada seleccionDeferPayment() permite al cliente seleccionar el tipo de aplazamiento con el que desea realizar el pago.

La aplicación debe guiar al cliente a través de instrucciones de interfaz de usuario claras y esperar a que el PIN pad complete el proceso de captura o informe un error o cancelación.

Etapa 3: Procesamiento de autorización

Después de la captura exitosa de la tarjeta, el Get Mini Android SDK transmite los datos de transacción cifrados al servidor utilizando el protocolo P.U.P.

Mientras la autorización está en progreso:

• La transacción debe considerarse en vuelo.
• La aplicación no debe interrumpir el proceso.
• El PIN pad permanece bloqueado para la operación actual.

El tiempo de autorización depende de las condiciones de la red y los tiempos de respuesta del servidor. El SDK realiza esta operación de forma síncrona y devuelve un resultado definitivo una vez que el servidor ha aprobado o denegado la transacción.

Crítico: Todas las operaciones de red deben ejecutarse en un hilo en segundo plano, nunca en el hilo principal (hilo de UI) de Android.

Etapa 4: Finalización y manejo de resultados

Cuando se recibe la respuesta de autorización, el SDK finaliza la operación y devuelve un objeto RedCLSOperativeWithCardResponse que contiene:

• status: Código entero que indica éxito (0) o error.
• Response: Cadena que contiene la respuesta XML del servidor (si es exitosa).
• msgKO: Descripción del error (si falló).
• stackTraceKO: Traza de excepción (si falló).
• transactionData: Un objeto RedCLSTransactionData con detalles de transacción analizados que incluyen:
  • Número de tarjeta (enmascarado), vencimiento, nombre del titular
  • Importe de la transacción, moneda, número de orden
  • Código de autorización y código de respuesta
  • Identificador de transacción (RTS)
  • Datos específicos de EMV (si corresponde)
  • Banderas de impresión de recibos y literales
  • Datos de DCC (si corresponde)

La aplicación debe:

1. Verificar el campo status para determinar si la operación tuvo éxito.
2. Para transacciones aprobadas, extraer el transactionData para la impresión de recibos y el mantenimiento de registros.
3. Para transacciones denegadas, mostrar el mensaje de error apropiado de msgKO o responseCode.

Después de la finalización, la aplicación puede:

• Mantener la conexión del PIN pad abierta para procesar transacciones adicionales (recomendado para operaciones consecutivas), o
• Cerrar explícitamente la conexión llamando a cerrarConexiones() para liberar recursos del PIN pad.

En esta etapa, el ciclo de vida de la transacción está completo.

Comunicación del estado de la transacción

El Get Mini Android SDK comunica el progreso y los resultados de la transacción a través de llamadas de método síncronas que devuelven objetos de respuesta estructurados.

Cada operación devuelve:

• Un código de estado que indica éxito o fallo.
• Una descripción del resultado o error.
• Datos de transacción detallados cuando corresponda (a través de RedCLSTransactionData).

Si ocurre un error en cualquier etapa, el ciclo de vida termina inmediatamente y el control vuelve a la aplicación. Los escenarios de fallo comunes incluyen:

• Pérdida de conexión del PIN pad durante la interacción (devolución de llamada pinPadNoEncontrado()).
• Cancelación del cliente durante la entrada del PIN.
• Errores de red durante la autorización.
• Estados de terminal o configuración inválidos.

Las aplicaciones deben interpretar los códigos de error (definidos en RedCLSErrorCodes) cuidadosamente y proporcionar retroalimentación de usuario apropiada u opciones de reintento cuando sea seguro hacerlo.

Mejores prácticas de gestión de conexión

• Sesión única, múltiples transacciones: Si procesas múltiples pagos consecutivos, mantén la conexión e inicialización del PIN pad activas entre transacciones para mejorar el rendimiento.
• Seguimiento del estado de conexión: Mantén el estado para determinar si se requiere conexión e inicialización antes de cada operación.
• Errores de Inicio de Sesión: Verifica la conectividad a Internet. El Get Mini Android SDK debe comunicarse con el servidor de pagos para validar las credenciales.
• Limpieza adecuada: Siempre llama a cerrarConexiones() al salir del flujo de pago o cuando la aplicación esté en segundo plano.

Notas de versión del SDK

Esta descripción del ciclo de vida se aplica a:

• Get Mini Android SDK 2.5.x: Implementación de referencia actual

Las versiones anteriores siguen el mismo flujo conceptual pero pueden diferir en las firmas de métodos y las características admitidas.

Recursos relacionados

• Seguridad y Vinculación de Dispositivos: Asociación de terminales, inicio de sesión transparente y gestión de claves.
• Inicio Rápido: Tu Primera Venta: Ejemplo de extremo a extremo que cubre el inicio de sesión, la inicialización del PIN pad y la ejecución del pago.