Início Rápido: Sua Primeira Venda

Este tutorial orienta você pelos passos essenciais para processar sua primeira transação de pagamento usando o Get Mini SDK. Você inicializará o ambiente do SDK, fará login como estabelecimento (merchant), conectará a um dispositivo PIN pad físico e executará uma transação de venda com tratamento de resultados baseado em delegate.

Requisitos

Antes de começar, certifique-se de ter:

SDK integrado no seu projeto Xcode com as linker flags -ObjC e -lsqlite3 configuradas
Protocolos do External Accessory adicionados ao seu Info.plist (ex: com.datecs.pinpad)
Credenciais de teste fornecidas pelo Get Mini: FUC (Merchant ID), Terminal ID, Chave de Licença (License Key) e credenciais de login
Dispositivo iOS físico para testes (O Simulator não suporta comunicação Bluetooth com PIN pad)
Dispositivo PIN pad Bluetooth ligado e dentro do alcance

Você deve concluir Instalar o SDK e Configurar Permissões do iOS antes de prosseguir com este tutorial.

Processo de Pagamento

Esta seção guia você por todo o fluxo de pagamento, desde a inicialização até o tratamento do resultado da transação.

Passo 1: Inicializar o Ambiente do SDK

O SDK deve ser inicializado com sua license key e ambiente de destino antes de qualquer operação. Essa configuração normalmente ocorre no seu AppDelegate ou em uma classe gerenciadora de pagamentos dedicada:

// Import via Bridging Header: CommonUtils.h
func initializeSDK() {
    // Set environment: "des" (Development), "int" (Integration), "ccal" (Pre-production), "real" (Production)
    CommonUtils.setEntorno("des")

    // Set your license key provided by Get Mini
    CommonUtils.setAppLicense("YOUR_LICENSE_KEY")
}

Chame este método de inicialização em application(_:didFinishLaunchingWithOptions:) antes de qualquer operação do SDK. A configuração de ambiente determina a quais servidores do Gateway do Get Mini o SDK se conecta para processar as transações.

Sempre use o ambiente de teste ("des") durante o desenvolvimento. Mude para produção ("real") apenas quando implantar em ambientes produtivos com credenciais de produção válidas.

Antes de processar transações, recupere a configuração do estabelecimento do Get Mini. A operação de login retorna os dados do estabelecimento (FUC, Terminal, etc.) necessários para as operações de pagamento:

// Import via Bridging Header: DatosLoginDTO.h, RedsysConfigurationManager.h
func performMerchantLogin() {
    let loginDTO = DatosLoginDTO(user: "your_username", andPass: "your_password")

    RedsysConfigurationManager.obtenerDatosComercioLogin(loginDTO) { result, error in
        if let merchantData = result {
            print("Login successful for: \(merchantData.nombreComercio ?? "Merchant")")
            // Store merchantData for use in payment operations
            self.saveMerchantData(merchantData)
        } else {
            print("Login failed: \(error?.localizedDescription ?? "Unknown error")")
        }
    }
}

O objeto DatosLoginResponseDTO retornado em caso de sucesso contém configurações essenciais do estabelecimento, incluindo FUC, Terminal ID e outras configurações necessárias para criar o objeto MerchanDTO para o processamento de pagamentos.

Passo 3: Implementar Protocolos de Delegate

Sua view controller deve estar em conformidade com os protocolos de delegate do SDK para receber callbacks durante a inicialização e o processamento de pagamentos. Adicione os protocolos necessários à declaração da sua classe:

// Import via Bridging Header: RedsysPinpadManager.h
class PaymentViewController: UIViewController,
                             RedsysDelegateGeneric,
                             RedsysBTPinpadInitDelegate,
                             RedsysBTPinpadPaymentDelegate {

    var pinpadManager: RedsysPinpadManager!
    var selectedDevice: Any?
    var pinpadConfig: PinpadConfig?

    override func viewDidLoad() {
        super.viewDidLoad()
        // Manager initialization will happen when starting the payment flow
    }

    // MARK: - Init Delegate Methods

    func onInitFinished(_ result: Any!, orError error: Error!) {
        if let config = result as? PinpadConfig {
            print("PinPad initialized successfully")
            self.pinpadConfig = config
            // Proceed to payment
        } else {
            print("Initialization failed: \(error?.localizedDescription ?? "")")
        }
    }

    // MARK: - Payment Delegate Methods

    func onPaymentProcess(_ result: Any!, orError error: Error!) {
        // Called during payment processing to notify progress
        print("Payment in progress...")
    }

    func onPaymentFinished(_ result: RespuestaTransaccionDTO!, orError error: Error!) {
        if let transaction = result, error == nil {
            print("Sale Approved! Auth Code: \(transaction.codigoAutorizacion ?? "")")
        } else {
            print("Sale Failed: \(error?.localizedDescription ?? "")")
        }
    }
}

Os métodos do delegate fornecem callbacks em diferentes estágios: onInitFinished confirma que o PIN pad está pronto, onPaymentProcess notifica sobre atualizações de progresso e onPaymentFinished entrega o resultado final da transação.

Passo 4: Inicializar o Gerenciador do PIN pad

Crie a instância do gerenciador do PIN pad e inicialize-a para comunicação Bluetooth:

func startPaymentFlow() {
    // Initialize manager with Bluetooth technology
    pinpadManager = RedsysPinpadManager(bluetoothTech: "GENERAL")

    // Get available Bluetooth devices
    let availableDevices = pinpadManager.bluetoothDevicesList()

    guard let devices = availableDevices as? [Any], !devices.isEmpty else {
        print("No PinPad devices found")
        return
    }

    // Select first available device
    selectedDevice = devices[0]

    // Configure the selected device
    connectAndConfigureDevice()
}

func connectAndConfigureDevice() {
    // Create MerchanDTO from login response
    let merchantDTO = MerchanDTO()
    merchantDTO.fuc = "999008881"  // From DatosLoginResponseDTO
    merchantDTO.fucExtendido = "999008881"
    merchantDTO.terminal = "001"
    merchantDTO.password = "your_password"

    // Connect and configure the device
    pinpadManager.connectAndConfigureDevice(selectedDevice,
                                           merchan: merchantDTO,
                                           withDelegate: self)
}

O gerenciador busca por dispositivos Bluetooth pareados e estabelece uma conexão. O método delegate onInitFinished será chamado quando o dispositivo estiver pronto para transações.

Passo 5: Executar o Pagamento

Uma vez que o PIN pad é inicializado (confirmado em onInitFinished), crie o DTO de pagamento e execute a transação:

func executePayment() {
    guard let config = pinpadConfig else {
        print("PinPad not initialized")
        return
    }

    // Create payment DTO
    let amount: Float = 10.50  // Amount in currency units
    let pagoDTO = PagoDTO(
        valor: Int(amount * 100),  // Convert to cents
        mMoneda: 978,              // ISO 4217 code (978 = EUR)
        nFactura: "TEST\(Int.random(in: 1000...9999))",  // Unique invoice number
        email: "",
        tlfCliente: "",
        datosPropietarios: ""
    )

    // Create MerchanDTO (same as in Step 4)
    let merchantDTO = MerchanDTO()
    merchantDTO.fuc = "999008881"
    merchantDTO.fucExtendido = "999008881"
    merchantDTO.terminal = "001"
    merchantDTO.password = "your_password"

    // Execute payment
    pinpadManager.payWithPinpadBluetooth(
        selectedDevice,
        merchan: merchantDTO,
        config: config,
        andPagoDTO: pagoDTO,
        withDelegate: self
    )
}

O SDK gerencia o fluxo completo da transação, incluindo a solicitação de inserção do cartão, a digitação do PIN, a comunicação com o Gateway de pagamento e o retorno do resultado através do callback delegate onPaymentFinished.

Parâmetro	Tipo	Descrição
`valor`	Int	Valor da transação em centavos (ex: 1050 para €10.50)
`mMoneda`	Int	Código ISO 4217 da moeda (978 = EUR, 840 = USD)
`nFactura`	String	Número único da fatura/pedido para rastreamento

Passo 6: Lidar com os Resultados da Transação

Processe o resultado da transação no callback delegate onPaymentFinished:

func onPaymentFinished(_ result: RespuestaTransaccionDTO!, orError error: Error!) {
    if let transaction = result, error == nil {
        // Transaction successful
        let authCode = transaction.codigoAutorizacion ?? ""
        let amount = transaction.importeTotal ?? ""

        print("Payment Approved")
        print("Auth Code: \(authCode)")
        print("Amount: \(amount)")

        // Save to database
        saveTransaction(authCode: authCode, amount: amount)

        // Show success message
        showSuccessAlert(authCode: authCode)
    } else {
        // Transaction failed
        print("Payment Failed: \(error?.localizedDescription ?? "")")
        showErrorAlert(message: error?.localizedDescription ?? "Transaction failed")
    }
}

Sempre salve o código de autorização (codigoAutorizacion) das transações bem-sucedidas. Este código é necessário para estornos e conciliação.

Solução de Problemas

Crash na Inicialização do RedsysPinpadManager

Verifique se a linker flag -ObjC está adicionada em Other Linker Flags. A ausência desta flag causa travamentos (crashes) de “Selector not recognized”.

Nenhum Dispositivo PIN pad Encontrado

Certifique-se de que UISupportedExternalAccessoryProtocols no Info.plist inclui o protocolo correto para o seu dispositivo (ex: com.datecs.pinpad para dispositivos Itos/Castles). Confirme se o dispositivo está pareado em Configurações do iOS > Bluetooth.

Erro de Ambiente Durante o Login

Se o login falhar com erros de ambiente, verifique se CommonUtils.setEntorno está definido como "des" para credenciais de teste ou "real" para credenciais de produção. O ambiente deve corresponder às suas credenciais.

Próximos Passos

Agora que você processou com sucesso seu primeiro pagamento, explore recursos adicionais do SDK:

Visão Geral do SDK iOS - Aprenda sobre suporte multivendor e recursos de segurança
Configurar Permissões do iOS - Revise todos os protocolos e permissões obrigatórios