Fluxo de uso da biblioteca

O Zoop iOS SDK facilita a adição de pagamentos de cartão de crédito/débito ao seu aplicativo para dispositivos móveis. Esta biblioteca nativa para Android permite que você colete informações de cartão sem ter que lidar com dados sensíveis que passam por seus servidores.

Procedimento de Pareamento

O procedimento de pareamento de terminais deve ser realizado diretamente nas configurações do Sistema Operacional. Para isso, acesse a opção "Ajustes" de seu dispositivo iOS, seguido por Bluetooth.

Ligue a maquininha e aperte o botão 0 (zero) para que ela possa ser descoberta para o pareamento. O identificador PAX-​SerialNumber ​deve aparecer na seção "Outros Dispositivos" que aparece no fim da lista de dispositivos Bluetooth. Selecione esta opção e digite em seu iOS o número de 6 dígitos que aparece na maquininha e seu terminal estará pareado.

Implementando métodos para seleção de maquininha

Para que seja possível identificar a conexão de desconexão de maquininhas, você deve registrar sua aplicação para a notificação destes tipos de evento. Para isso, basta adicionar as seguintes linhas de código:

class AppDelegate: UIResponder, UIApplicationDelegate, DeviceProtocol {

  func deviceDidConnect(device: Device) {
         print(“Conectado acessorio: \(device.getName())“)
         goToTransactionViewController()
     }

     func deviceDidDisconnect(device: Device) {
         print(“Removido acessorio: \(device.getName())“)
         goToDevicesViewController()
     }

     func devicesListDidUpdate() {
         print(“devicesListDidUpdate”)
         NotificationCenter.default.post(name: Notification.Name(“ZSDK_DEVICE_LIST_UPDATED”), object: nil)
     }

     let deviceManager: DevicesManager = DevicesManager.shared

     var window: UIWindow?

     override init() {

         super.init()

         deviceManager.setDeviceListener(deviceListener: self)
     }
     
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        return true
    }
    
    private func goToTransactionViewController() {
        if let currentViewController = AppDelegate.getCurrentViewController() as? DevicesViewController {
            currentViewController.performSegue(withIdentifier: "PresentTestTransactionSegue", sender: currentViewController)
        }
 
    }

    private func goToDevicesViewController() {
        AppDelegate.getNavigationController()?.popToRootViewController(animated: true)

    }

    func applicationWillResignActive(_ application: UIApplication) {
       }

    func applicationDidEnterBackground(_ application: UIApplication) {
         }

    func applicationWillEnterForeground(_ application: UIApplication) {
         }

    func applicationDidBecomeActive(_ application: UIApplication) {
      
    }

    func applicationWillTerminate(_ application: UIApplication) {
    
    }

  
     
}
let deviceManager: DevicesManager = DevicesManager.shared

NotificationCenter.default.addObserver(self, selector: #selector(listShouldUpdate), name: Notification.Name(“ZSDK_DEVICE_LIST_UPDATED”), object: nil)

Note que as callbacks de conexão e desconexão também devem ser implementadas em sua aplicação. A seguir os exemplos implementadas em nossa aplicação de demonstração:

func getAccessoryIdentifiers() -> [String]{
       let name = deviceManager.getConnectedDevicesList().map { $0.getName() }
       print(“listando device -> \(name)“)
       return name
}

Para selecionar a maquininha desejada você deve chamar o método deviceManager.selectDevice(device: device)

Implementando métodos para realizar uma transação

Para utilizar a funcionalidade de cobrança do Zoop iOS SDK, você chamará 1 método e implementará 3 protocolos. Para processar cartões de magstripe, outras interfaces/callbacks serão definidas/usadas para responder às necessidades específicas do cartão.

Implementação de TerminalPaymentProtocol

Implemente o protocolo ​TerminalPaymentProtocol para receber notificações de status de transação, solicitações e resultados finais de carga/transação.

Todos os métodos serão explicados com mais detalhes nas seguintes linhas:

  • func paymentFailed(var1:AnyObject)
    Notifica o aplicativo que uma cobrança / transação falhou.

  • func paymentSuccessful(var1:AnyObject)
    Notifica a aplicação de que uma cobrança foi aprovada.

  • func paymentAborted()
    Notifica o aplicativo de que a carga solicitada foi abortada com sucesso após a solicitação do usuário.

  • func cardholderSignatureRequested()
    Notifica o aplicativo de que é necessário capturar a assinatura do titular do cartão.

  • func currentChargeCanBeAbortedByUser(var1:Bool)
    Notifica o aplicativo quando pode-se solicitar o cancelamento de uma transação em andamento ou não. Isso pode ser utilizado para implementar uma interface de usuário que reflita melhor as condições internas da API de Pagamento Zoop (gateway) (pode cancelar, botão ativado, não pode cancelar, o botão está desabilitado).

  • func paymentDuplicated(var1: AnyObject)
    Esse método notifica sua aplicação que uma carga/transação é duplicada. Essa função deve ser solicitada previamente ao suporte. Para configurar o intervalo mínimo para a trava de duplicação.

  • func signatureResult(var1: Int)
    Esse método é um callback que informa se a assinatura foi adicionada com sucesso no comprovante. Em caso de sucesso, seu parâmetro é igual a '0' (zero).

🚧

Quick disclaimer

Cancelar o crédito de uma transação de cartão depois de aprovada pode ter impacto na forma como um risco de vendedor é marcado por empresas de processamento de cartão de crédito. Assim, uma vez que o pedido foi concluído e enviado para processamento, o cancelamento só poderá ser realizado depois, através uma operação de estorno. E a interface do usuário aceita cancelar antes de qualquer coisa ter sido enviada para o gateway de pagamento para processamento, de modo que este tipo de interface auxilie o entendimento do usuário.

Implementação ApplicationDisplayProtocol

Implemente o protocolo ​ApplicationDisplayProtocol para solicitar que o aplicativo apresente mensagens ao usuário.

O protocolo tem 2 métodos. Todos serão explicados com mais detalhes nas seguintes linhas:

  • func showMessage(var1:String, var2:TerminalMessageType)
    Permite que o aplicativo apresente uma mensagem para o usuário.

  • func showMessage(var1:String, var2:TerminalMessageType, var3:String)
    Permite que o aplicativo apresente uma mensagem e uma explicação ao usuário.

  • Classe ZoopTerminalPayment

Para realizar uma carga/transação, deve-se criar uma nova instância do ZoopTerminalPayment e "setar" os seus "listerners":

let zoopTerminalPayment = ZoopTerminalPayment()
zoopTerminalPayment.setTerminalPaymentListener(ptpl: self) zoopTerminalPayment.setApplicationDisplayListener(padl: self) zoopTerminalPayment.setExtraCardInformationListener
(pExtraCardInformationListener: self)

❗️

Importante

A interface ExtraCardInformationListener é descrita na seção Respostas para a aplicação.

Uma vez instanciado o ZoopTerminalPayment podemos chamar o método charge que efetivamente realiza a carga/transação:

charge(valueToCharge: Double, paymentOption: EMVConnectiOS.PaymentType, iNumberOfInstallments: Int, marketplaceId: String, sellerId: String, publishableKey: String)
  • valueToCharge - o valor a ser cobrado no formato BigDecimal

  • paymentOption - int representando a opção de pagamento. Pode assumir os valores: 0 (zero) - crédito; 1 - débito; 2 - crédito parcelado; 3 - voucher

  • iNumberOfInstallments - int representando o número de parcelas para dividir o valor cobrado

  • marketplaceId - String contendo o identificador registrado para o marketplace atual

  • sellerId - String contendo o identificador do vendedor registrado

  • publishableKey - chave de identificação em String

A seguir, um exemplo de código:

zoopTerminalPayment.charge(valueToCharge: Double(1.00), paymentOption: 0, iNumberOfInstallments: 1, marketplaceId: "ffffa5eeee47cccc8b22229d7777a3bb", sellerId: "8989894eee3434530909e9234565bffd", publishableKey: "zk_test_jhUYGlLGlOPPoF23FFoaRODf")

🚧

Sobre as Credenciais

Sua integração requer chaves de API diferentes para cada ambiente: Teste e Produção. Especialmente em produção, você deverá manter suas chaves seguras, em hipótese alguma compartilhe suas chaves de API com qualquer pessoa. Para fazer transações de pagamento, você também precisará do marketplace_Id correspondente e o seller_Id com quem seu marketplace está fazendo transações em nome dele. Você pode obter essas credenciais de API com nossa equipe de suporte em: [email protected].

Interceptando as logs de erros

A partir da versão 2.1.8 do SDK iOS será possível que sua aplicação intercepte a log de erros durante o processo de charge/void e use esta log da forma que for mais adequada para o seu contexto.

Para ter acesso aos logs implemente a interface LogInterceptorListener no AppDelegate. Esta implementação exige a adição de um método void dump(string log) o qual vai receber em tempo real o callback contendo as ocorrências de log ocorridas. Você pode usar estas logs para debugar e/ou analisar ocorrências durante a execução.