# Ciclo de Vida da Transação

Processar uma transação de cartão presente (card-present) com o Get Mini SDK envolve interação coordenada entre seu aplicativo iOS, o Gateway do Get Mini e o hardware físico do PIN pad. Entender este ciclo de vida ajuda você a criar experiências de pagamento robustas com feedback adequado ao usuário, tratamento de erros e gerenciamento de tempo limite (timeout).

O SDK gerencia o processamento de transações em quatro fases distintas: **Inicialização e Autenticação** (Initialization & Authentication), **Descoberta de Hardware** (Hardware Discovery), **Execução da Transação** (Transaction Execution) e **Finalização do Resultado** (Result Finalization). Cada fase envolve operações específicas e transições de estado comunicadas por meio de callbacks de delegate.

## Fases da Transação

### Fase 1: Inicialização e Autenticação

Antes de interagir com o hardware, o SDK deve estabelecer sua identidade e o contexto do estabelecimento (merchant).

**Configuração do Framework**

Seu aplicativo configura o ambiente e a licença do SDK usando `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 configuração determina quais servidores do Gateway do Get Mini processam as transações e valida a autorização do seu aplicativo para usar o SDK.

**Login do Estabelecimento**

O aplicativo executa a autenticação do estabelecimento usando `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
    }
}
```

O `DatosLoginResponseDTO` retornado contém os dados essenciais do estabelecimento, incluindo FUC (Merchant ID) e Terminal ID, necessários para o processamento do pagamento.

<Callout type="note">

O SDK também suporta "Login Transparente" (Login sin credenciales) para terminais pré-configurados que não requerem a inserção de credenciais baseada em interface de usuário (UI).

</Callout>

### Fase 2: Descoberta de Hardware (External Accessory)

Diferente dos dispositivos Bluetooth genéricos, o Get Mini SDK se comunica com os PIN pads por meio do **External Accessory framework** do iOS.

**Correspondência de Protocolos**

O SDK apenas descobre dispositivos que correspondem às strings de protocolo declaradas no seu `Info.plist` em `UISupportedExternalAccessoryProtocols`. Por exemplo, `com.datecs.pinpad` para dispositivos Itos/Castles ou `com.ingenico.*` para leitores Ingenico. Sem essas declarações, o iOS bloqueia o SDK de detectar o hardware.

**Descoberta de Dispositivos**

O `RedsysPinpadManager` busca por dispositivos External Accessory pareados:

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

Isso retorna um array de objetos `EAAccessory` representando os PIN pads físicos atualmente pareados em Configurações > Bluetooth do iOS e que correspondem aos protocolos declarados.

**Conexão e Configuração**

Uma vez que um dispositivo é selecionado, o SDK estabelece uma sessão e o configura com os dados do estabelecimento:

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

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

O callback de delegate `onInitFinished` confirma o sucesso da conexão e retorna um objeto `PinpadConfig` necessário para as operações de pagamento.

### Fase 3: Execução da Transação

Uma vez que o PIN pad está conectado e configurado, seu aplicativo inicia o pagamento criando um `PagoDTO` e chamando o método de pagamento.

**Configuração do Pagamento**

Crie o objeto de transferência de dados de pagamento com os detalhes da transação:

```
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">

Os valores devem ser passados como números inteiros representando centavos (multiplique por 100) para garantir a precisão em diferentes escalas de moedas.

</Callout>

**Interação com o Cartão**

Execute o pagamento, o que aciona o fluxo completo da transação:

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

O PIN pad assume o controle da interação com o usuário:

1. **Solicita** ao cliente para inserir (Insert), passar (Swipe) ou aproximar (Tap) seu cartão
2. **Lê** os dados do cartão via chip, aproximação (contactless/NFC) ou tarja magnética
3. **Digitação do PIN**: Se necessário, o cliente digita seu PIN no teclado físico do hardware

> **Nota de Segurança**: A digitação do PIN ocorre inteiramente dentro do elemento seguro de hardware do PIN pad. O PIN nunca entra na memória do dispositivo iOS ou no seu aplicativo.

**Criptografia e Gateway**

O PIN pad criptografa os dados do cartão usando Criptografia de Ponta a Ponta (E2EE) baseada em hardware. O SDK transmite este payload criptografado para os servidores do Gateway do Get Mini, que descriptografam, processam e encaminham a transação para a bandeira do cartão e o banco emissor para autorização.

### Fase 4: Finalização e Assinatura

O Gateway retorna uma resposta entregue por meio do `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
    }
}
```

**Autorização Padrão**

Para transações aprovadas, o `RespuestaTransaccionDTO` contém um código de autorização que confirma o processamento bem-sucedido do pagamento. Salve este código para operações de estorno (refund) e conciliação.

**Assinatura Obrigatória**

Se o portador do cartão não se autenticou via PIN, a resposta indica a necessidade de assinatura através do campo `AutenticadoPorPin`:

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

Isso comumente ocorre com cartões offline ou fluxos específicos de cartões internacionais. Seu aplicativo deve capturar a assinatura digital do cliente (como uma imagem) e enviá-la para cumprir os requisitos legais:

```
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 Transição de Estado

A tabela a seguir ilustra o fluxo de estado interno durante o processamento da transação:

| Estado | Gatilho | Ação |
| :---- | :---- | :---- |
| **Ready** | `setAppLicense` called | SDK inicializado e ocioso |
| **Login** | `obtenerDatosComercioLogin` called | Autenticando credenciais do estabelecimento |
| **Discovery** | `bluetoothDevicesList` called | Buscando por dispositivos EAAccessory pareados |
| **Connecting** | `connectAndConfigureDevice` called | Estabelecendo sessão com o PIN pad |
| **Interaction** | `payWithPinpadBluetooth` called | Solicitado ao usuário que apresente o cartão/digite o PIN |
| **Authorizing** | Card data captured | Payload criptografado enviado ao Gateway |
| **Signature** | `AutenticadoPorPin == false` | Captura de assinatura opcional obrigatória |
| **Finished** | Gateway response received | Callback `onPaymentFinished` acionado |

## Principais Restrições

Entender as restrições do ciclo de vida ajuda você a projetar experiências de pagamento confiáveis:

**Operação Síncrona**

Apenas uma operação de pagamento pode estar ativa por vez por instância do `RedsysPinpadManager`. Tentar iniciar uma nova transação enquanto outra está em andamento causa conflitos de estado no SDK e possíveis envios duplicados. Implemente o bloqueio da interface do usuário (indicadores modais) durante transações ativas para evitar múltiplas tentativas de pagamento.

**Persistência do Bluetooth**

Se a conexão Bluetooth cair durante a execução da transação, o SDK tenta a reconexão automática. Se a reconexão falhar, um callback de erro é acionado com um código de timeout de conexão. Monitore o callback `onPaymentProcess` para atualizações de progresso e trate os erros de conexão de forma adequada.

**Formatação de Valores**

Os valores devem ser passados como números inteiros representando centavos para garantir a precisão:

| Valor | Formato | Valor PagoDTO |
| :---- | :---- | :---- |
| €10.50 | 10.50 * 100 | `1050` |
| €100.00 | 100.00 * 100 | `10000` |
| \$25.99 | 25.99 * 100 | `2599` |

Isso evita problemas de precisão de ponto flutuante em diferentes escalas de moedas e garante o processamento preciso da transação.

**Protocolos de External Accessory**

O SDK se comunica apenas com dispositivos que correspondam aos protocolos declarados no `Info.plist`. A ausência de declarações de protocolo impede totalmente a descoberta de dispositivos — o iOS bloqueia o SDK de detectar o hardware do PIN pad sem essas entradas.

## Próximos Passos

* [Início Rápido: Sua Primeira Venda](/pt/get-mini/ios-sdk/first-steps/ios-sdk-quickstart) - Implemente o fluxo completo da transação passo a passo
* [Configurar Permissões do iOS](/pt/get-mini/ios-sdk/first-steps/configure-ios-permissions) - Configure os protocolos obrigatórios do External Accessory