Tap On

📘

Importante

No Tap On, a princípio, serão aplicadas as taxas padrão, sem possibilidade de negociação. Para mais detalhes, entre em contato com nosso time Comercial.

O PagBank Tap On é uma extensão para Android 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 Intent do Android. Seu app envia um bundle com os dados da transação para o aplicativo PagBank Tap On, que deve estar previamente instalado no dispositivo do vendedor.

A documentação da extensão Tap On inclui os seguintes tópicos:

• Primeiros Passos
• Iniciar uma Transação
• Receber o Resultado da Transação
• Fluxo de Estorno
• Fluxo de Login (Opcional)
• Fluxo de Logout (Opcional)
• Customização Visual (Opcional)

Fluxo Resumido

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

1. Criação da Transação: Seu aplicativo cria e envia uma Intent para o app Tap On, contendo os dados da transação em um objeto TapOnPaymentData serializado em JSON.
2. Processamento no Tap On: O aplicativo Tap On assume o fluxo de pagamento, processa a transação e retorna o resultado da transação (TransactionResult) para o seu app.
3. Tratamento do Retorno: Seu aplicativo recebe o resultado da transação e finaliza a jornada de pagamento.

📘

Requisito de Login

Na primeira venda, o vendedor deve realizar login utilizando uma conta PagBank ao iniciar o passo 2 (Processamento no Tap On). O aplicativo Tap On inicia automaticamente o fluxo de login antes de iniciar a transação, se necessário.

Pré-requisitos

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

📘

Prática recomendada

Crie um fluxo em seu aplicativo que oriente o usuário a baixar a extensão Tap On na Google Play para realizar as vendas, no momento da venda e/ou integração. A extensão pode ser encontrada neste link.

Após a instalação, o vendedor precisa fazer o login em sua conta PagBank ao realizar a primeira venda.

Iniciar uma Transação

Para processar um pagamento, seu aplicativo deve construir uma Intent direcionada ao app Tap On, contendo um bundle com os dados da transação serializados em JSON.

Configuração da Intent

A Intent deve ser configurada com a ação e o pacote de destino correspondente (Produção ou Testes/QA).

A chave utilizada para o bundle da Intent de início da transação é TAP_ON_PAYMENT_DATA. Esta chave deve ser passada como um putExtra da Intent, contendo o JSON do objeto TapOnPaymentData, como demonstrado no exemplo a seguir:

val intent = Intent("br.com.uol.ps.tapon.OPEN_APP")
        .addCategory(Intent.CATEGORY_DEFAULT)
        .setPackage("br.com.uol.ps.tapon")
        .putExtra("TAP_ON_PAYMENT_DATA", json)

📘

O uso de .setPackage(...) na Intent é obrigatório por segurança, evitando a interceptação da Intent por aplicativos maliciosos.

Objeto de Envio: TapOnPaymentData

Os dados da transação são definidos pelo objeto TapOnPaymentData, que deve ser serializado para o formato JSON. A definição do objeto TapOnPaymentData é descrita pela seguint classe:

data class TapOnPaymentData(
    val appKey: String, // Identificador único fornecido pelo PagBank.
    val appName: String, // Nome do seu aplicativo parceiro (ex: "SmartPOS").
    val appVersion: String, // Versão do seu aplicativo (ex: "1.0.0").
    val androidId: String, // ANDROID_ID do app parceiro.
    val saleAmount: Double, // Valor da transação em Reais (ex: 125.50).
    val themeSettings: TapOnThemeConfigModel? // Objeto para customização visual de cores (opcional).
)

A tabela a seguir descreve os campos necessários para iniciar uma transação com o Tap On.

Caso não seja informada uma appKey válida, o Tap On não será capaz de se comunicar com os serviços e a transação não poderá ser realizada. Nesse caso, todas as chamadas de inicialização retornarão o código HTTP 403 (Forbidden).

Abaixo, um exemplo da mensagem de erro que será exibida neste cenário:

Receber o Resultado da Transação

Após o processamento, o Tap On retorna o resultado para seu aplicativo através do método onActivityResult.

Transação Bem-Sucedida

Se o pagamento for concluído com sucesso, o resultado virá no onActivityResult na chave resultTapOnSuccessJson. O valor desse extra é uma String no formato JSON do objeto TransactionResult:

@Parcelize
data class TransactionResult(
    val saleValue: Double?,
    val paymentMethod: String?,
    val transactionCode: String?,
    val transactionDateTime: String?,
    val cardHolder: String?,
    val cardBrand: String?,
    val installments: Int?,
    val installmentValue: Double?,
    val installmentMethod: String?
) : Parcelable

A tabela a seguir descreve o objeto TransactionResult:

O bloco de código a seguir apresenta um exemplo completo considerando a execução da transação e do tratamento do retorno.

private const val REQUEST_CODE_TAP_ON = 1234

// 1. Inicia a transação com Tap On
private fun initTapOn(amount: Double) {
    val paymentData = TapOnPaymentData(
        appKey = "app-key",
        appName = "MeuApp",
        appVersion = "1.0.0",
        androidId = Settings.Secure.getString(contentResolver, Settings.Secure.ANDROID_ID),
        saleAmount = amount,
        themeSettings = themeSettings
    )

    // Serializa o objeto para JSON
    val json = Gson().toJson(paymentData)

    // Cria e dispara a Intent
    val intent = Intent("br.com.uol.ps.tapon.OPEN_APP")
        .addCategory(Intent.CATEGORY_DEFAULT)
        .setPackage("br.com.uol.ps.tapon")
        .putExtra("TAP_ON_PAYMENT_DATA", json)

    startActivityForResult(intent, REQUEST_CODE_TAP_ON)
}

// 2. Trata o resultado recebido do Tap On
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == REQUEST_CODE_TAP_ON) {
        if (resultCode == RESULT_OK && data?.hasExtra("resultTapOnSuccessJson") == true) {
            // Deserializa o JSON de retorno para o objeto TransactionResult
            val transactionJson = data.getStringExtra("resultTapOnSuccessJson")
            val transaction = Gson().fromJson(transactionJson, TransactionResult::class.java)

            if (transaction != null && !transaction.transactionCode.isNullOrBlank()) {
                // Processar sucesso da transação aqui...
            }
        }
    }
}

Fluxo de Estorno

O processo de estorno também é iniciado via Intent, permitindo que seu app solicite a devolução de um pagamento diretamente ao Tap On. Todos os dados necessários para a realização do estorno devem ser encapsulados no objeto TapOnVoidPaymentData.

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

• O pacote do Tap On precisa estar instalado no dispositivo.
• A comunicação deve usar startActivityForResult.
• É necessário informar os dados obrigatórios no objeto TapOnVoidPaymentData.
• Um UUID único deve ser gerado para identificar a solicitação de estorno.

O exemplo abaixo demonstra como construir a Intent de estorno usando o objeto TapOnVoidPaymentData.

private fun initRefund() {
        val refund = TapOnVoidPaymentData(
            refCode = UUID.randomUUID().toString(),
            transactionCode = "AAD73AB2-9442-49AD-BC1C-7389157D0100",
            amount = 3.84,
            appKey = "102eb6cf-7e1d-40f1-acc0-610ac16b60ab",
            appName = "PartnerApp",
            appVersion = "1.0.0",
            androidId = "92e5a54c6e785f30",
            themeSettings = tapOnTheme
        )
        val intent = Intent(TapMapKey.PATH_APP_TAP_ON_OPEN).setFlags(0)
            .addCategory(Intent.CATEGORY_DEFAULT)
            .setPackage(provideTapOnPath())
            .putExtra(TapMapKey.KEY_BUNDLE_TAP_ON_REFUND_PAYMENT_DATA, Gson().toJson(refund))
        startActivityForResult(intent, TapMapKey.REQUEST_CODE_TAP_ON)
    }
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == TapMapKey.REQUEST_CODE_TAP_ON) {
            when (resultCode) {
                Activity.RESULT_OK -> {
                    // ✅ Estorno finalizado com sucesso
                    // Faça o tratamento de sucesso aqui
                }
            }
        }}

Fluxo de Login - Segregado do Fluxo de Pagamento (Opcional)

Este fluxo permite que as aplicações parceiras chamem o login do Tap On para configurar o ambiente do vendedor sem a necessidade de realizar uma venda atrelada à autenticação. Desta forma, é possível criar fluxos apartados para incentivar a configuração do Tap On ou verificar credenciais antes de iniciar o fluxo transacional.

⚠️

Atenção

Este fluxo está disponível a partir da release 3.26.0 do app Tap On - Extensão. Caso já utilize a extensão e queira implementar este fluxo, será necessário validar a versão instalada antes de permitir a navegação.

Configuração da Intent de Configuração

Este cenário possui uma implementação similar ao fluxo de pagamento, porém utiliza uma Action e uma chave de Bundle diferentes.

📘

Importante

O uso de .setPackage(...) na Intent é obrigatório por segurança.

Objeto de Envio: ConfigData

Os dados para configuração devem ser enviados através do objeto ConfigData.

data class ConfigData(
    val appKey: String, // Identificador único fornecido pelo PagBank.
    var appName: String?, // Nome do app parceiro (ex: SmartPOS).
    val appVersion: String, // Versão do app parceiro (ex: 1.0.0).
    val androidId: String, // Identificador ANDROID_ID do app parceiro.
    val themeSettings: TapOnThemeConfigModel?, // Customização visual (opcional).
    var configureAction: String? = null // Ação de configuração. Para login, deve ser "LOGIN".
)

Os campos são descritos a seguir:

• appKey: Identificador único fornecido pelo PagBank após o processo de integração.
• appName: Nome do app parceiro (ex: SmartPOS).
• appVersion: Versão do app parceiro (ex: 1.0.0).
• androidId: Identificador ANDROID_ID do app parceiro.
• themeSettings: Customização visual (opcional).
• configureAction: Define a ação a ser executada. Para este fluxo, é obrigatório passar o valor "LOGIN".

🛑

Erro de Configuração

Caso configureAction não seja passado ou esteja incorreto, a aplicação retornará uma tela de erro para o usuário final.

Resultado do Login

Recomenda-se a criação de um requestCode diferente do utilizado no fluxo de pagamento.

• Sucesso: Retorna RESULT_OK. Indica que o login foi realizado com sucesso.
• Cancelamento/Erro: Retorna RESULT_CANCELED. Indica que o usuário retornou ou ocorreu um erro no fluxo.

Fluxo de Logout (Opcional)

Caso a aplicação parceira necessite controlar múltiplos acessos e garantir que o usuário logado no Tap On corresponda ao usuário autenticado no app parceiro, é possível realizar o logout explicitamente.

⚠️

Atenção

Assim como o fluxo de login segregado, este recurso está disponível a partir da release 3.26.0.

Implementação do Logout

Para realizar o logout, utiliza-se a mesma estrutura do Fluxo de Login Segregado descrito acima. A única diferença reside no preenchimento do objeto ConfigData:

• configureAction: Deve ser preenchido com o valor "LOGOUT".

Ao receber o RESULT_OK neste fluxo, a sessão do usuário no Tap On terá sido encerrada.

Customização Visual (Opcional)

Você pode personalizar a aparência da interface do Tap On para que ela se alinhe à identidade visual do seu aplicativo. Para isso, você precisa criar e enviar o objeto TapOnThemeConfigModel dentro do TapOnPaymentData.

O bloco de código abaixo apresenta as opções de configuração:

@Parcelize
data class TapOnThemeConfigModel(
    val toolbarTextColor: Int, // Cor do texto da barra de ferramentas
    val toolbarColor: Int, // Cor de fundo da barra de ferramentas
    val statusBarColor: Int, // Cor da barra de status
    val buttonBackgroundColor: Int, // Cor de fundo dos botões principais
    val buttonTextColor: Int // Cor do texto dos botões principais
) : Parcelable

A tabela a seguir descreve os Parâmetros disponíveis para customizar a aparência:

A seguir você encontra um exemplo de uso da customização da interface.

val themeSettings = TapOnThemeConfigModel(
    toolbarTextColor = ContextCompat.getColor(this, R.color.white),
    toolbarColor = ContextCompat.getColor(this, R.color.primary),
    statusBarColor = ContextCompat.getColor(this, R.color.status_bar),
    buttonBackgroundColor = ContextCompat.getColor(this, R.color.primary_dark),
    buttonTextColor = ContextCompat.getColor(this, R.color.white)
)

Como iniciar a integração com a extensão 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. Reunião técnica
   Após a aprovação comercial, será agendada uma reunião técnica com a equipe de integração, onde será apresentada a jornada de desenvolvimento e esclarecidas as dúvidas iniciais. pós a reunião nós
   iremos providenciar a geração e envio de sua AppKey de Testes (QA). Ela é necessária para iniciar o desenvolvimento com a extensão de pagamentos Tap On.
3. Desenvolvimento
   Após a reunião inicial realizada e com a AppKey de QA disponibilizada, você poderá iniciar a integração utilizando a nossa extensão 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.
4. Homologação
   Quando sua aplicação estiver finalizada, será necessário abrir um chamado para solicitar a homologação do aplicativo através do formulário de atendimento. Nesta etapa, será necessário fornecer informações que serão utilizadas para validar o .apk.
5. Disponibilização da soluçã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 abaixo para requisitar suporte ao time PagBank. Você estará dando o primeiro passo para se tornar nosso parceiro.
Integrações | PagSeguro Internet S.A