Tap On - iOS

O PagBank Tap On é um SDK para iOS que permite que seu aplicativo aceite pagamentos por aproximação (NFC). A comunicação entre seu aplicativo e o Tap On é realizada por meio de uma framework, que recebe os dados da transação e deve estar embarcada no app do vendedor.

Link de download da framework: biblioteca de integração para vendas com Tap On PagBank para parceiros.

A documentação do SDK Tap On para iOS inclui os seguintes tópicos:

• Pré-requisitos
• Instalação da framework
• Fluxo resumido
• Como iniciar o SDK do Tap On
• Fluxo de Ativação
• Fluxo de Venda
• Fluxo de Estorno
• Fluxo de Logout
• Estado de ativação do Tap On
• Customização Visual (Opcional)
• Exemplo completo

Pré-requisitos

Antes de iniciar a integração, garanta que o ambiente atenda aos seguintes requisitos:

Instalação da framework

A inclusão da dependência TapOnPartner.xcframework pode ser feita de duas maneiras:

Opção 1: Inclusão do arquivo .xcframework no app iOS

1. Baixe a última release e descompacte no diretório do projeto do app que integrará o Tap On iOS.
2. No Xcode, nas configurações do seu Target, inclua o TapOnPartner.xcframework em Frameworks, Libraries, and Embedded Content.

Opção 2: Inclusão com CocoaPods

No seu Podfile, adicione o source e a dependência do Tap On iOS:

source "ssh://[email protected]/pagseguro/pagbank-tapon-partner-ios.git"

# ...

pod 'TapOnPartner'

Fluxo resumido

O fluxo de integração é simples e direto, necessitando que você execute as seguintes operações:

1. Inicialização: seu aplicativo importa o SDK do Tap On e inicializa a classe TapOnPayment, passando um objeto TapOnPartnerConfiguration com a appKey.
2. Assinatura do delegate: seu aplicativo assina o delegate da classe TapOnPayment, que implementa o protocolo TapOnPartnerDelegate, responsável por receber o resultado da transação (paymentStatusEvent) ou do estorno (cancelStatusEvent).
3. Tratamento do retorno: seu aplicativo processa o retorno para finalizar a jornada de pagamento ou de estorno.

Como iniciar o SDK do Tap On

A integração ocorre por meio da classe TapOnPayment, que recebe na inicialização um objeto TapOnPartnerConfiguration contendo a appKey.

// Inicialização com appKey
let configuration = TapOnPartnerConfiguration(appKey: "YOUR_APP_KEY")
let tapOn = TapOnPayment(configuration)

tapOn.delegate = self

Objeto de configuração: TapOnPayment

Objeto de configuração: TapOnPartnerConfiguration

Esta classe define o identificador do integrador a ser enviado para o SDK Tap On.

public struct TapOnPartnerConfiguration {
    public var appKey: String

    public init(appKey: String) {
        self.appKey = appKey
    }
}

Objeto de configuração: TapOnPaymentDataSource

Protocolo que deve ser implementado para definir quais features ficam ligadas ou desligadas no Tap On.

Fluxo de Ativação

O fluxo de ativação permite que apps parceiros façam a ativação do Tap On de forma separada da venda. A comunicação ocorre via SDK.

Para que o fluxo de ativação seja executado, os seguintes requisitos devem ser atendidos:

• A comunicação deve ser feita pelo método activate da classe TapOnPayment.
• O argumento presentStyle: PresentStyle determina o modo de apresentação das telas do Tap On. As opções são present(UIViewController) ou push(UINavigationController).

tapOn.activate(.present(viewController))

Resultado da ativação

Ao concluir a ativação, o resultado virá na implementação do protocolo TapOnPartnerDelegate, no método activateStatusEvent, que devolve o booleano successfully: Bool informando o sucesso ou a falha da ativação.

func activateStatusEvent(successfully: Bool) {
    print("Activate with success: \(successfully)")
}

Fluxo de Venda

O fluxo de venda permite que apps parceiros integrem diretamente com o Tap On para realizar pagamentos. A comunicação ocorre via SDK, e os dados necessários são enviados no objeto TapOnPaymentModel.

Para que o fluxo de venda seja executado, os seguintes requisitos devem ser atendidos:

• A aplicação parceira deve configurar corretamente os dados obrigatórios do objeto.
• A comunicação deve ser feita pelo método payment da classe TapOnPayment.
• O argumento presentStyle: PresentStyle determina o modo de apresentação das telas do Tap On. As opções são present(UIViewController) ou push(UINavigationController).

Objeto de envio: TapOnPaymentModel

Este objeto define os dados da transação a ser enviada para o SDK Tap On.

import Foundation

public struct TapOnPaymentModel {
    public init(amount: Double) {
        self.amount = amount
    }

    var amount: Double
}

// Iniciando o pagamento de R$ 10,00
let payment = TapOnPaymentModel(amount: 10.00)

tapOn.payment(payment, .present(viewController))

Resultado da transação

Caso a transação seja concluída com sucesso, o resultado virá na implementação do protocolo TapOnPartnerDelegate, no método paymentStatusEvent, que informa o enum approved(TapOnPaymentResult) com o objeto TapOnPaymentResult contendo todas as informações da transação.

func paymentStatusEvent(_ event: TapOnPartner.TapOnPartnerPaymentEvent) {
    switch event {
    case .approved(let result):
        print("paymentResult: \(result)")
    case .failure(let error):
        print("Error: \(error)")
    }
}

Objeto de retorno: TapOnPaymentResult

public struct TapOnPaymentResult: Codable {
    public var transactionCode: String?
    public var responseMessage: String
    public var originalAmount: String?
    public var amount: String
    public var installments: Int
    public var paymentType: String
    public var cardBrand: String?
    public var holder: String
    public var authDate: String
    public var authCode: String?
    public var userRef: String?
}

Fluxo de Estorno

O fluxo de estorno permite que apps parceiros integrem diretamente com o Tap On para realizar estornos de pagamentos. A comunicação ocorre via SDK, e os dados necessários são enviados no objeto TapOnCancelPaymentModel.

Para que o fluxo de estorno seja executado, os seguintes requisitos devem ser atendidos:

• A aplicação parceira deve configurar corretamente os dados obrigatórios do objeto.
• transactionCode e amount devem ser informados para identificação do estorno.
• A comunicação deve ser feita pelo método cancelPayment da classe TapOnPayment.

Objeto de envio: TapOnCancelPaymentModel

Este objeto define os dados do estorno da transação a ser enviado para o SDK Tap On.

import Foundation

public struct TapOnCancelPaymentModel {
    public var transactionCode: String
    public var amount: String
    public var userRef: String?

    public init(transactionCode: String, amount: String, userRef: String? = nil) {
        self.transactionCode = transactionCode
        self.amount = amount
        self.userRef = userRef
    }
}

let cancelPayment = TapOnCancelPaymentModel(transactionCode: "TRANSACTION_CODE", amount: "1000")

tapOn.cancelPayment(cancelPayment, .present(controller))

Resultado do estorno

Caso o estorno seja concluído com sucesso, o resultado virá na implementação do protocolo TapOnPartnerDelegate, no método cancelStatusEvent, que informa o enum approved(TapOnCancelResult) com o objeto TapOnCancelResult contendo todas as informações do estorno.

func cancelStatusEvent(_ event: TapOnPartner.TapOnPartnerCancelEvent) {
    switch event {
    case .approved(let result):
        print("cancelResult: \(result)")
    case .failure(let error):
        print("Error: \(error)")
    }
}

Objeto de retorno: TapOnCancelResult

public struct TapOnCancelResult {
    public var amount: String
    public var refCode: String
}

Fluxo de Logout

Ao realizar o logout no seu app, é necessário realizar o logout no Tap On também, evitando inconsistências e perfis distintos dentro do mesmo fluxo.

Para que o fluxo de logout seja executado, os seguintes requisitos devem ser atendidos:

• A aplicação parceira deve realizar a chamada de logout do Tap On dentro do fluxo de logout do seu app.
• A comunicação deve ser feita pelo método logout da classe TapOnPayment.

tapOn.logout()

Estado de ativação do Tap On

O SDK retorna a informação sobre o estado de ativação do Tap On, permitindo identificar rapidamente se um vendedor está com o Tap On ativado ou não.

Para consultar o estado de ativação, os seguintes requisitos devem ser atendidos:

• A aplicação parceira deve realizar a chamada do método que retorna o estado de ativação do Tap On.
• A comunicação deve ser feita pelo método isActive da classe TapOnPayment.
• O retorno do método é Bool.

if tapOn.isActive() {
    // Do something
}

Customização Visual (Opcional)

Você pode personalizar a interface de pagamento para que ela se alinhe à identidade visual do seu aplicativo. Para isso, crie uma struct implementando o protocolo UIColorPartner, como no exemplo abaixo:

struct ExampleColors: UIColorPartner {
    var action: UIColor { UIColor.orange }
    var actionLight: UIColor { UIColor.red }
    var actionHigh: UIColor { UIColor.green }
    var actionDark: UIColor { UIColor.gray }
    var brand: UIColor { UIColor.brown }
    var onBrand: UIColor { UIColor.magenta }
    var neutral: UIColor { UIColor.purple }
    var success: UIColor { UIColor.darkGray }
    var warning: UIColor { UIColor.black }
    var error: UIColor { UIColor.systemPink }
    var product: UIColor { UIColor.yellow }
}

O objeto de cores é passado como último argumento dos métodos payment e cancelPayment.

// Criando uma variável com as cores
let colors = ExampleColors()

// Iniciando o pagamento de R$ 10,00
let payment = TapOnPaymentModel(amount: 10.00)

tapOn.payment(payment, .present(viewController), colors)

// Criando uma variável com as cores
let colors = ExampleColors()

// Iniciando o estorno
let cancelPayment = TapOnCancelPaymentModel(transactionCode: "TRANSACTION_CODE", amount: "1000")

tapOn.cancelPayment(cancelPayment, .present(controller), colors)

Exemplo completo

O bloco de código a seguir apresenta um exemplo completo considerando a inicialização do SDK, a venda, o estorno, a ativação e o logout.

import TapOnPartner
import SwiftUI

class ExampleViewModel: ObservableObject {

    var tapOn: TapOnPayment?

    var rootController: UIViewController? = {
        if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
           let window = windowScene.windows.first {
            if let controller = window.rootViewController {
                return controller
            }
        }
        return nil
    }()

    @MainActor
    func initTapOn() {
        let configuration = TapOnPartnerConfiguration(appKey: "YOUR_APP_KEY")
        self.tapOn = TapOnPayment(configuration)
        self.tapOn?.delegate = self
        self.tapOn?.prepareTap()
    }

    @MainActor
    func payment(amount: Double) {
        if let controller = rootController {
            let colors = ExampleColors()
            let payment = TapOnPaymentModel(amount: amount)
            tapOn?.payment(payment,
                           .present(controller),
                           colors)
        }
    }

    @MainActor
    func cancelPayment() {
        if let controller = rootController {
            let colors = ExampleColors()
            let cancelPayment = TapOnCancelPaymentModel(transactionCode: "TRANSACTION_CODE",
                                                        amount: "1000",
                                                        userRef: "12345")
            tapOn?.cancelPayment(cancelPayment,
                                 .present(controller),
                                 colors)
        }
    }

    @MainActor
    func logout() {
        tapOn?.logout()
        if let isActive = tapOn?.isActive() {
            print("Ativado? \(isActive)")
        }
    }

    @MainActor
    func activate() {
        if let controller = rootController {
            let colors = ExampleColors()
            tapOn?.activate(.present(controller),
                            colors)
        }
    }
}

extension ExampleViewModel: TapOnPartnerDelegate {

    func activateStatusEvent(successfully: Bool) {
        print("Activate with success: \(successfully)")
    }

    func paymentStatusEvent(_ event: TapOnPartner.TapOnPartnerPaymentEvent) {
        switch event {
        case .approved(let result):
            print("paymentResult: \(result)")
        case .failure(let error):
            print("Error: \(error)")
        }
    }

    func cancelStatusEvent(_ event: TapOnPartner.TapOnPartnerCancelEvent) {
        switch event {
        case .approved(let result):
            print("cancelResult: \(result)")
        case .failure(let error):
            print("Error: \(error)")
        }
    }
}

Como iniciar a integração com o SDK Tap On

Para iniciar o processo de integração com o Tap On do PagBank, siga os passos abaixo:

1. Contato comercial
   O primeiro passo é preencher o formulário de solicitação de parceria. Nossa equipe comercial entrará em contato para entender seu modelo de negócio e validar sua empresa junto ao time de PLD (Prevenção à Lavagem de Dinheiro).
2. Desenvolvimento
   Após a reunião inicial realizada e com a appKey disponibilizada, você poderá iniciar a integração utilizando o SDK de pagamentos Tap On. Durante esta fase, recomendamos que siga a documentação oficial e, caso tenha dúvidas, abra um chamado com o time de integração. Para solicitar suporte adicional, utilize o formulário de atendimento.
3. Disponibilização em produção
   Após a aprovação no processo de homologação, nós iremos gerar sua appKey de Produção. Ela será necessária para realizar transações no ambiente produtivo, conforme descrito em nossa documentação.

Suporte Tap On

Caso você necessite de suporte adicional em alguma das fases de desenvolvimento e integração da sua aplicação, utilize o formulário a seguir para requisitar suporte ao time PagBank, você estará dando o primeiro passo para se tornar nosso parceiro: Integrações | PagSeguro Internet S.A.