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)
• Repasse de taxas MDR (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, 
    val appName: String, 
    val appVersion: String, 
    val androidId: String, 
  	val saleAmount: Double, 
		val themeSettings: TapOnThemeConfigModel?,
		val enableTaxPassThrough: Boolean?
)

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

📘

A partir da release 3.33.0, foi disponibilizado o campo chamado enableTaxPassThrough, com ele habilitado, é possível visualizar o fluxo de repasse de taxas MDR, fazendo com que o comprador assuma todas as taxas.

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

Caso a transação seja concluída com sucesso, o resultado virá no onActivityResult na chave resultTapOnSuccessJson em uma String 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?,
		val isSaleWithTaxPassThrough: Boolean?
) : 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,
				enableTaxPassThrough = true
    )

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

⚠️

Requisito obrigatório

Para transações bem-sucedidas realizadas via Tap On Extensão, é obrigatório exibir o logotipo da bandeira do cartão no comprovante de venda ao retornar da aplicação Tap On Extensão para a aplicação parceira. Os logos de cada bandeira retornada no campo cardBrand podem ser encontrados em Bandeiras_Obrigatorias.zip.

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, 
    var appName: String?, 
    val appVersion: String, 
    val androidId: String, 
    val themeSettings: TapOnThemeConfigModel?, 
    var configureAction: String? = null
)

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.

Repasse de taxas MDR (Opcional)

O repasse de taxas permite que o vendedor transfira para o cliente os custos da transação, que são o MDR (Merchant Discount Rate) e as taxas de parcelamento, resultando em um acréscimo no valor final da venda.

A funcionalidade pode ser utilizada em:

• Débito
• Crédito à vista
• Crédito parcelado

O controle é feito por meio de um toggle apresentado na tela de seleção da forma de pagamento:

• Toggle ativado: as taxas são adicionadas ao valor final pago pelo cliente.
• Toggle desativado: as taxas são descontadas do valor recebido pelo vendedor.

O repasse é aplicado por transação, permitindo que o vendedor decida quando habilitar ou não a funcionalidade de acordo com sua lógica de negócio.

O repasse de taxas não estará disponível para vendedores que emitem nota fiscal nem para aqueles com precificação IC+, modelo em que a taxa é composta pelo custo real da transação, incluindo interchange e fees de bandeira, acrescido de um markup.

❗️

A exibição para vendedores que emitem nota fiscal deve ser controlada pela aplicação parceira por meio da flag enableTaxPassThrough.

Nos casos de toggle desativado ou modelo de precificação IC+, será apresentado a opção Parcelado Comprador, na qual o repasse ocorre apenas sobre as taxas de parcelamento, sem o MDR.

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 buttonBackgroundColor: Int,
    val buttonTextColor: Int
) : 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(
    buttonBackgroundColor = ContextCompat.getColor(this, R.color.primary_dark),
    buttonTextColor = ContextCompat.getColor(this, R.color.white)
)

⚠️

A partir da release 3.31.0, foi realizado alterações no design system da aplicação, portanto, campos que existiam relacionados a alteração de cores da toolbar deixaram de ser validados, com a finalidade de manter a construção de um design neutro.

Caso sua aplicação ainda esteja passando esses valores, esses campos serão ignorados pela aplicação Tap On Extensão.

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