Zoop Developer Center

Bem-vindo ao hub do desenvolvedor Zoop. Você encontrará guias da API e uma documentação abrangente para ajudá-lo a começar a trabalhar com a Zoop o mais rápido possível, além de ajudá-lo se você tiver algum problema. Vamos lá!

Documentação

Fluxo de uso da biblioteca

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

O processo de integração do SDK consiste em 3 etapas principais: configuração de projeto, pareamento de terminais e integração com funcionalidades.

Etapa 1 - Configuração de projeto (Adicionando o SDK ao seu projeto)

O SDK em si é um arquivo de estrutura única (EMVConnectiOS.framework) com todas as dependências necessárias. O framework EMVConnectiOS deve ser adicionado como um binário incorporado no seu arquivo de projeto iOS como mostrado na seguinte imagem.

Você também deve incluir o framework ExternalAccessory em seu projeto selecionando o botão '+' localizado na seção Linked Frameworks e bibliotecas. O framework ExternalAccessory permite que o aplicativo capture e manipule notificações sobre conexão e desconexão de terminal bluetooth.

Configurações para utilização de Bluetooth:

O aplicativo requer o registro do protocolo de comunicação do terminal do seu lado. Você deve adicionar dois itens para a chave para a chave "Supported external accessory protocols" no seu arquivo plist: "br.com.gertec.protocoloGertec" para suporte aos terminais da Gertec, como é o caso da MP5 e "com.paxsz.iPOS" para suporte aos terminais da PAX. Esta configuração é ilustrada pela seguinte imagem:

Além disso, caso deseje que a transação continue a ser executada mesmo quando sua aplicação não está visível (background mode), você deve adicionar a configuração "Required background modes" no arquivo plist do projeto, contendo o item "App communicates with an accessory". A configuração está expressa na imagem a seguir:

Etapa 2 - Pareamento de terminais

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

Implementação de listeners para conexão e desconexão de dispositivos

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 de callbacks 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)

  • Acesse ​Aplicação demonstração​ para obter o código da aplicação exemplo.

Etapa 3 - Integração com funcionalidades

COBRANÇA

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

Mais detalhes sobre o fluxo de integração abaixo:

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

O protocolo possui 6 métodos. 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).

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 - enviado para processamento - o cancelamento só pode 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.

Outros métodos foram adicionados para notificar os recibos enviados; confirmar assinatura recebida, entre outros.

2) Implementação ApplicationDisplayListener

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.

3) Cobrando um cartão (crédito, débito, outros)

Utilize o método ​charge de qualquer interface de terminal disponível para cobrar valores de cartões de crédito e débito.

public func charge(valueToCharge:Decimal, paymentOption:Int, iNumberOfInstallments:Int, marketplaceId:String, sellerId:String, publishableKey:String)

O primeiro parâmetro é um ​Double que representa o valor a ser cobrado. O segundo parâmetro é um número inteiro que representa a opção de pagamento, que pode assumir os valores 0 (para pagamento de crédito), 1 (para pagamento por débito) ou 2 (para pagamento por parcelamento).
O ​iNumberOfInstallments solicita o número de parcelas para dividir o valor cobrado. O parâmetro ​MarketPlaceId solicita o identificador registrado para o marketplace atual. SellerId, o identificador do vendedor registrado e ​publishableKey​ a chave de identificação.

A função de charge é um método da classe ​ZoopTerminalPayment​. Abaixo segue código para implementação do envio de uma transação.

self.zoopTerminalPayment?.setTerminalPaymentListener(ptpl: self) self.zoopTerminalPayment?.setApplicationDisplayListener(padl: self) self.zoopTerminalPayment?.setExtraCardInformationListener
(pExtraCardInformationListener: self) do {
try self.zoopTerminalPayment?.charge(valueToCharge: number, paymentOption: paymentOption, iNumberOfInstallments: nInstallments, marketplaceId: sMarketplaceId, sellerId: sSellerId, publishableKey: sPublishableKey)
} catch {
print("Erro ao enviar comando charge")
}