Otimizar Pagamento

Configure a inicialização do SDK e ative sessões antecipadamente para reduzir o tempo de processamento dos pagamentos Tap to Pay.

Inicialização do SDK

Para utilizar o plugin TapOnPhone, é necessário realizar a inicialização. Nessa etapa, o dispositivo é ativado automaticamente no ambiente Zoop — o processo leva entre 2 e 3 segundos.

💡
A inicialização também pode ser feita de forma automática ao iniciar um pagamento. Se o dispositivo não estiver inicializado, o SDK executará o processo internamente antes de iniciar a cobrança.

Passo 1: Inicializar o Kernel

O método initialize() executa de forma assíncrona e não bloqueia a thread atual. Pode ser chamado de qualquer thread, incluindo a main thread.

fun initialize(
    onSuccess: InitializeCallback,
    onError: ErrorCallback,
    onEvent: EventCallback
)

Tipos dos callbacks:

typealias InitializeCallback = (status: InitializationStatus) -> Unit
typealias ErrorCallback = (error: ErrorResponse) -> Unit
typealias EventCallback = (event: ApplicationEvent) -> Unit

Exemplo de inicialização:

TapOnPhone.initialize(
    onSuccess = { status ->
        when (status) {
            InitializationStatus.SUCCESS -> {
                Log.d("Init", "SDK inicializado com sucesso")
                // SDK pronto para uso
            }
            InitializationStatus.FAILED -> {
                Log.e("Init", "Falha na inicialização")
            }
            InitializationStatus.PROCESSING -> {
                Log.d("Init", "Inicialização em andamento")
            }
            InitializationStatus.NOT_INITIALIZED -> {
                Log.w("Init", "SDK não inicializado")
            }
        }
    },
    onError = { error ->
        Log.e("Init", "Erro: ${error.type}")
        when (error.type) {
            ErrorResponse.ErrorType.Initialize -> {
                // Erro durante a inicialização
            }
            ErrorResponse.ErrorType.Terminal -> {
                // Erro do terminal
            }
            else -> {
                // Outros tipos de erro
            }
        }
    },
    onEvent = { event ->
        Log.d("Init", "Evento: ${event.name}")
        // Acompanhar eventos em tempo real
    }
)

📌
Na versão 2.1.0, TapOnPhone é um singleton (object). Não é necessário instanciar a classe — use diretamente TapOnPhone.initialize(), TapOnPhone.pay(), etc.

Status de inicialização

O callback onSuccess retorna um valor do tipo InitializationStatus:

Status	Descrição
`SUCCESS`	Inicialização concluída com sucesso. SDK pronto para uso
`FAILED`	A inicialização falhou
`PROCESSING`	Inicialização em andamento
`NOT_INITIALIZED`	O método `initialize()` ainda não foi chamado

💡
Se TapOnPhone.isApplicationInitAllowed retornar false, ignore a inicialização — o ambiente não permite a ativação neste momento.

Obter o Instance ID

Após a inicialização bem-sucedida, você pode obter o ID da instância do terminal:

val instanceId = TapOnPhone.getInstanceId()

O instanceId só estará disponível após a inicialização bem-sucedida do terminal.

Ativação de Sessão

A ativação da sessão é uma etapa necessária para a execução do pagamento. Nela, o Kernel cria um objeto utilizado pelo SDK para realizar a transação.

Uso único

Cada sessão é utilizada apenas uma vez por transação e destruída ao final (sucesso ou erro).

Expiração

Sessões possuem tempo de expiração definido pelo Kernel. Após expirada, crie uma nova.

Gerenciamento automático

O SDK gerencia ativação e expiração automaticamente durante o fluxo de pagamento.

⚡
Por que ativar antecipadamente? A ativação envolve comunicação com serviços externos e pode levar alguns segundos. Ao chamar activateSession() antes do pagamento, a sessão já estará pronta quando o usuário iniciar a cobrança — resultando em uma experiência mais rápida.

Método `activateSession()`

A execução deste método é opcional. Se não for chamado, o SDK ativará a sessão automaticamente durante o fluxo de pagamento.

Callback	Descrição
`onSuccess`	Chamado quando a sessão é ativada com sucesso
`onError(ErrorResponse)`	Chamado quando há falha na ativação da sessão
`onEvent(ApplicationEvent)`	Notifica eventos emitidos durante o fluxo de ativação

Exemplo de ativação

fun activateSession() {
    TapOnPhone.activateSession(
        onSuccess = {
            Log.d("SessionActivation", "Session Activated!")
        },
        onError = { error ->
            handleSessionError(error)
        },
        onEvent = { event ->
            Log.d("SessionActivation", "Session event: ${event.name}")
        }
    )
}

Tratamento de erros da sessão

fun handleSessionError(error: ErrorResponse) {
    val sessionError = error.error
    when (sessionError) {
        is SessionErrorResponse -> {
            Log.d("SessionActivation", sessionError.message)
            // Verificar detalhes de attestation, se disponíveis
            sessionError.attestationStatus?.let {
                for (attestation in it) {
                    Log.d("status", attestation.status)
                    Log.d("timestamp", attestation.timestampUtc)
                    for (outcome in attestation.outcomes) {
                        Log.d(
                            "outcome",
                            "moniker[${outcome.moniker}] code[${outcome.statusCode}] reason[${outcome.reason}]"
                        )
                    }
                }
            }
            Log.d("SessionActivation", "kernel: ${sessionError.kernel?.description} ?: ")
        }
        is TapOnPhoneError -> {
            Log.d("Payment", sessionError.message ?: "Falha ao ativar sessão")
        }
        else -> {
            Log.d("Payment", "Falha ao ativar sessão")
        }
    }
}

Inicialização do SDK

Passo 1: Inicializar o Kernel

Status de inicialização

Obter o Instance ID

Ativação de Sessão

Método activateSession()

Exemplo de ativação

Tratamento de erros da sessão

Método `activateSession()`