# 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.

<Callout type="note">

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).

</Callout>

### 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: ""
)
```

<Callout type="warning">

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.

</Callout>

**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:

1. **Solicita** al cliente que inserte (Insert), deslice (Swipe) o acerque (Tap) su tarjeta
2. **Lee** los datos de la tarjeta a través del chip, el pago sin contacto (contactless/NFC) o la banda magnética
3. **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](/es/get-mini/ios-sdk/first-steps/ios-sdk-quickstart) - Implementa el flujo completo de la transacción paso a paso
* [Configurar Permisos de iOS](/es/get-mini/ios-sdk/first-steps/configure-ios-permissions) - Configura los protocolos de External Accessory requeridos