Ciclo de vida de la transacción

Procesar una transacción de tarjeta presente (card-present) con el SDK de Get Mini implica una interacción coordinada entre tu aplicación iOS, el Gateway de Get Mini y el hardware físico del PIN pad. Comprender este ciclo de vida te ayuda a construir experiencias de pago robustas con los comentarios (feedback) adecuados para el usuario, gestión de errores y control de tiempos de espera (timeout).

El SDK gestiona el procesamiento de transacciones a través de cuatro fases distintas: Inicialización y Autenticación (Initialization & Authentication), Descubrimiento de Hardware (Hardware Discovery), Ejecución de la Transacción (Transaction Execution) y Finalización y Firma (Result Finalization & Signature). Cada fase conlleva operaciones específicas y transiciones de estado que se comunican a través de callbacks de delegados.

Fases de la transacción

Fase 1: Inicialización y autenticación

Antes de interactuar con el hardware, el SDK debe establecer tu identidad y el contexto del comercio (merchant).

Configuración del Framework

Tu aplicación fija el entorno de ejecución y la licencia de la aplicación utilizando CommonUtils:

// Set environment: "des" (Development), "int" (Integration),
// "ccal" (Pre-production), "real" (Production)
CommonUtils.setEntorno("des")

// Set App License provided by Get Mini
CommonUtils.setAppLicense("YOUR_LICENSE_KEY")

Esta configuración determina qué servidores del Gateway de Get Mini procesan las transacciones y valida la autorización de tu aplicación para utilizar el SDK.

Obtención de datos de comercio

La aplicación realiza la autenticación del comercio utilizando RedsysConfigurationManager:

let loginDTO = DatosLoginDTO(user: "username", andPass: "password")

RedsysConfigurationManager.obtenerDatosComercioLogin(loginDTO) { result, error in
    if let merchantData = result {
        // Store FUC, Terminal ID, and other merchant configuration
    }
}

El DatosLoginResponseDTO devuelto contiene datos esenciales del comercio (a través de merchantList), incluyendo el FUC y el número de terminal de cada TerminalDataDTO, requeridos para el procesamiento del pago.

El SDK también soporta el “Login Transparente” (Login sin credenciales) para terminales preconfigurados que no requieren la introducción de credenciales a través de la interfaz de usuario (UI).

Fase 2: Descubrimiento de hardware (External Accessory)

A diferencia de los dispositivos Bluetooth genéricos, el SDK de Get Mini se comunica con los PIN pads a través del External Accessory framework de iOS.

Coincidencia de Protocolos

El SDK solo descubre dispositivos que coinciden con las cadenas de protocolo declaradas en tu Info.plist bajo UISupportedExternalAccessoryProtocols. Por ejemplo, com.datecs.PIN pad para dispositivos Itos o com.ingenico.* para lectores Ingenico. Sin estas declaraciones, iOS bloquea al SDK para que no detecte el hardware.

Descubrimiento de Dispositivos

El RedsysPinpadManager busca dispositivos External Accessory emparejados:

let pinpadManager = RedsysPinpadManager(bluetoothTech: "pinpadBluetooth")
let availableDevices = pinpadManager.bluetoothDevicesList()

Esto devuelve un array de objetos EAAccessory que representan los PIN pads físicos actualmente emparejados en Ajustes > Bluetooth de iOS y que coinciden con los protocolos declarados.

Conexión y Configuración

Una vez que se selecciona un dispositivo, el SDK establece una sesión y lo configura con los datos del comercio:

let merchantDTO = MerchanDTO()
merchantDTO.fuc = "999008881"
merchantDTO.terminal = "001"

pinpadManager.connectAndConfigureDevice(selectedDevice,
                                       merchan: merchantDTO,
                                       withDelegate: self)

El callback del delegado onInitFinished confirma que la conexión ha sido exitosa y devuelve un objeto PinpadConfig necesario para las operaciones de pago.

Fase 3: Ejecución de la transacción

Una vez que el PIN pad está conectado y configurado, tu aplicación inicia el pago creando un PagoDTO y llamando al método de pago.

Configuración del Pago

Crea el objeto de transferencia de datos de pago con los detalles de la transacción:

let amount: Float = 10.50
let pagoDTO = PagoDTO(
    valor: Int(amount * 100),  // Amount in cents (1050 for €10.50)
    mMoneda: 978,              // ISO 4217 currency code (978 = EUR)
    nFactura: "ORDER001",      // Unique invoice/order number
    email: "",
    tlfCliente: "",
    datosPropietarios: ""
)

Los importes deben pasarse como números enteros que representen céntimos (multiplique por 100) para asegurar la precisión en diferentes escalas de divisas.

Interacción con la Tarjeta

Ejecuta el pago, lo cual desencadena el flujo completo de la transacción:

pinpadManager.payWithPinpadBluetooth(
    selectedDevice,
    merchan: merchantDTO,
    config: pinpadConfig,
    andPagoDTO: pagoDTO,
    withDelegate: self
)

El PIN pad asume el control de la interacción con el usuario:

Solicita al cliente que inserte (Insert), deslice (Swipe) o acerque (Tap) su tarjeta
Lee los datos de la tarjeta a través del chip, el pago sin contacto (contactless/NFC) o la banda magnética
Introducción del PIN: Si es requerido, el cliente introduce su PIN en el teclado físico del hardware

Nota de Seguridad: La introducción del PIN ocurre completamente dentro del elemento seguro de hardware del PIN pad. El PIN nunca entra en la memoria del dispositivo iOS ni en tu aplicación.

Encriptación y Gateway

El PIN pad encripta los datos de la tarjeta utilizando Encriptación de Extremo a Extremo (E2EE) basada en hardware. El SDK transmite este payload encriptado a los servidores del Gateway de Get Mini, los cuales desencriptan, procesan y reenvían la transacción a la red de la tarjeta y al banco emisor para su autorización.

Fase 4: Finalización y firma

El Gateway devuelve una respuesta entregada a través de RedsysBTPinpadPaymentDelegate:

func onPaymentFinished(_ result: RespuestaTransaccionDTO!, orError error: Error!) {
    if let transaction = result, error == nil {
        let authCode = transaction.codigoAutorizacion
        // Transaction approved
    } else {
        // Transaction failed or declined
    }
}

Autorización Estándar

Para las transacciones aprobadas, el RespuestaTransaccionDTO contiene un código de autorización que confirma el procesamiento exitoso del pago. Guarda este código para operaciones de reembolso (refund) y conciliación.

Firma Obligatoria

Si el titular de la tarjeta no se autenticó mediante PIN, la respuesta indica el requisito de firma a través del campo AutenticadoPorPin:

if let transaction = result, transaction.AutenticadoPorPin == false {
    // Capture digital signature
    captureSignature()
}

Esto suele ocurrir con tarjetas offline o flujos específicos de tarjetas internacionales. Tu aplicación debe capturar la firma digital del cliente (como una imagen) y enviarla para cumplir con los requisitos legales:

let signatureDTO = EnvioFirmaDTO(
    withTerminal: terminalDataDTO,  // TerminalDataDTO with FUC and Terminal
    withFirma: signatureImage,      // UIImage of captured signature
    Format: 2,                      // Format: 1=BMP, 2=JPG, 3=TIF, 4=GIF
    andOperacion: operationDTO      // OperacionDTO from transaction
)

RedsysConfigurationManager.envioFirmaDigitalizada(signatureDTO) { result, error in
    // Signature submission complete
}

Mapa de transición de estado

La siguiente tabla ilustra el flujo de estado interno durante el procesamiento de la transacción:

Estado	Desencadenante	Acción
Ready	`setAppLicense` called	SDK inicializado y en reposo (idle)
Login	`obtenerDatosComercioLogin` called	Autenticando las credenciales del comercio
Discovery	`bluetoothDevicesList` called	Buscando dispositivos EAAccessory emparejados
Connecting	`connectAndConfigureDevice` called	Estableciendo sesión con el PIN pad
Interaction	`payWithPinpadBluetooth` called	Se solicita al usuario que presente la tarjeta/introduzca el PIN
Authorizing	Datos de la tarjeta capturados	Payload encriptado enviado al Gateway
Signature	`AutenticadoPorPin == false`	Se requiere captura opcional de la firma
Finished	Respuesta del Gateway recibida	Callback `onPaymentFinished` invocado

Restricciones clave

Comprender las restricciones del ciclo de vida te ayuda a diseñar experiencias de pago fiables:

Operación Síncrona

Solo una operación de pago puede estar activa a la vez por cada instancia de RedsysPinpadManager. Intentar iniciar una nueva transacción mientras hay una en curso provoca conflictos de estado en el SDK y posibles envíos duplicados. Implementa el bloqueo de la interfaz de usuario (indicadores modales) durante las transacciones activas para evitar múltiples intentos de pago.

Persistencia de Bluetooth

Si la conexión Bluetooth se interrumpe durante la ejecución de la transacción, el SDK intenta la reconexión automática. Si la conexión no puede restablecerse, se produce un error de conexión. Monitoriza el callback onPaymentProcess para conocer las actualizaciones de progreso y gestiona los errores de conexión adecuadamente.

Formato de Importes

Los importes deben pasarse como números enteros que representen céntimos para garantizar la precisión:

Importe	Formato	Valor PagoDTO
€10.50	10.50 * 100	`1050`
€100.00	100.00 * 100	`10000`
$25.99	25.99 * 100	`2599`

Esto evita problemas de precisión de coma flotante en diferentes escalas de divisas y garantiza un procesamiento preciso de las transacciones.

Protocolos de External Accessory

El SDK solo se comunica con dispositivos que coincidan con los protocolos declarados en Info.plist. La falta de declaraciones de protocolos impide por completo el descubrimiento de dispositivos; iOS bloquea al SDK para que no detecte el hardware del PIN pad sin estas entradas.

Próximos pasos

Inicio Rápido: Tu Primera Venta - Implementa el flujo completo de la transacción paso a paso
Configurar Permisos de iOS - Configura los protocolos de External Accessory requeridos