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.

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

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:

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:

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 - Implemente o fluxo completo da transação passo a passo
• Configurar Permissões do iOS - Configure os protocolos obrigatórios do External Accessory