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

Pré-requisitos

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

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

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