Tratamento de erros

Durante a integração do Tap on Phone, podem ocorrer erros caso algum passo não seja executado corretamente, por exemplo, falha na inicialização do SDK ou envio de valores inválidos para uma transação.

ℹ️
O parceiro integrador deve preparar sua aplicação para mapear os erros e notificar o usuário da melhor forma possível.

1. Exibição de telas de erro

Em vista disso, para tornar mais claro ao usuário o motivo do erro ocorrido, o SDK do Tap on Phone conta com telas de erro padronizadas. Essas telas seguem o mesmo padrão visual e de usabilidade, alterando apenas o conteúdo exibido, conforme o tipo de erro identificado.

A estrutura da tela é composta pelos seguintes elementos:

2. Inicialização do SDK

O código de inicialização segue o padrão abaixo:

val tapOnPhoneSdk = TapOnPhone.getInstance()
  tapOnPhoneSdk.initialize(
  context = this,
  config,
  onInitializeStart = {},
  onInitializeSuccess = {},
  onInitializeFailure = {exception -> },
  useDefaultLoading = false,
  )

Caso ocorra algum problema durante a inicialização, o callback onInitializeFailure será acionado, retornando uma exception com o tipo de falha ocorrido.

A seguir, listamos as possíveis exceptions que podem ser retornadas, divididas em dois grupos:

Com tela (exibem mensagem padrão ao usuário);
Sem tela (devem ser tratadas pela aplicação integradora.

3. Exceptions da inicialização

Exceptions com tela

Essas exceptions disparam automaticamente uma tela informativa padrão ao usuário final.

Exceptions Descrição

Exceptions	Descrição
`ProblemToInitializerException`	Usado quando o método `initialize` é chamado e ocorre um erro por motivos diversos, exibindo uma mensagem genérica para o usuário do app. Exemplos: regras do servidor como segurança, validação de cliente, validação de versão ou integração com terceiros (ex.: Cielo).

ProblemToInitializerException

Usado quando o método initialize é chamado e ocorre um erro por motivos diversos, exibindo uma mensagem genérica para o usuário do app.

Exemplos: regras do servidor como segurança, validação de cliente, validação de versão ou integração com terceiros (ex.: Cielo).

Exceptions sem tela

Essas exceptions não exibem interface automaticamente.

Exceptions	Descrição
`CheckIsTerminalActiveException`	Quando o método `initialize` é chamado, e durante o processo de ativação do terminal houver algum erro para verificar ou criar o terminal para o pagamento.
`SecurityCheckException`	Usado quando ocorre falha na coleta de informações de segurança. Esse item pode ser emitido em todos os métodos menos no `initJourney`.
`VersionInvalidException`	Usado quando a versão usada do SDK não é mais válida, sendo necessário realizar a atualização do SDK.
`WhiteLabelException`	Quando ocorre alguma falha no whiteLabel, como falha ao encontrar o arquivo JSON ou erro na sintaxe do arquivo.
`DeviceIncompatibleException`	Quando o dispositivo não é compatível com as regras do SDK. Segue abaixo um enum do que poderá ser retornado pela exception.

enum class DeviceIncompatibleEnum {
 DEVICE_IS_EMULATOR, //O dispositivo usado é um emulador
 DEVICE_IS_ROOT, //O dispositivo está com root
 DEVICE_IS_DEV_MODE, //O dispositivo está com o modo de desenvolvimento ativo
 DEVICE_PROBLEM_WITH_NFC, //Ocorreu um problema com o NFC
 DEVICE_WITH_VERSION_OS_INCOMPATIBLE, //O dispositivo está com o SO android inferior ao mínimo
 DEVICE_WITH_HOOK_DETECTED, // Caso dispositivo possua alguma instrumentação hook será bloqueado o fluxo
 }

4. Erros no transacional

Após o initialize do SDK, o parceiro pode iniciar o fluxo de pagamento por meio da função initPayment ou cancelamento através de initCancellation.

val tapOnPhoneSdk = TapOnPhone.getInstance()
tapOnPhoneSdk.initPayment(
  context = this,
  config,
  onPaymentStart = {},
  onPaymentSuccess = {},
  onPaymentFailure = {callback, exception -> },
  onNewSale = {}
)

Caso a função initPayment seja chamada sem informar corretamente os valores no parâmetro initialData, como price, paymentMethod ou installments, será lançada a seguinte exception em onPaymentFailure.

Exceptions	Descrição
`InitialDataInvalidException`	Valores do `initialData` informados incorretamente.
`InvalidMerchantOrderIdException`	Valor informado no parâmetro `merchantOrderId` fora do padrão (não numérico ou fora de 1 a 15 dígitos).

5. Callback do transacional

Os erros retornados pelo onPaymentFailure podem ser divididos entre:

Callbacks com tela implementada (o SDK exibe mensagem padrão ao usuário) ;
Callbacks sem tela (devem ser tratados pela aplicação integradora).

Callbacks com tela

Essas exceptions disparam automaticamente uma tela informativa padrão ao usuário final.

Callback	Descrição
`PAYMENT_CANCEL`	Ocorre quando o usuário cancela a transação durante a etapa de aproximação do cartão, resultando na interrupção do fluxo e na invalidação do pagamento.
`TIME_EXPIRED`	Ocorre quando o tempo limite para concluir o pagamento é atingido durante a etapa de aproximação do cartão.
`WITHOUT_SPACE_IN_DISK`	Quando não há espaço livre para o armazenamento da transação no `initPayment`.
`PROBLEM_GENERIC`	Será invocado quando houver falha não especificada durante a tentativa de concluir o pagamento.
`PROBLEM_TO_MAKE_TRANSACTION`	Será invocado quando houver algum erro não esperado ao iniciar a tentativa de concluir o pagamento.

Callback sem tela

Esses callbacks não exibem interface automaticamente. É responsabilidade da aplicação integradora capturar o evento e definir como informar o usuário ou registrar o erro internamente.

Callback	Descrição
`PROBLEM_TO_INITIALIZER`	Quando a função `initPayment` ou `initCancellation` é chamada, e houve um erro na inicialização.
`TRANSACTION_BIGGER_OR_EQUALS_THEN_45_DAYS`	Ocorre quando é solicitado o cancelamento de uma transação cuja data ultrapassa o limite de 45 dias.
`TRANSACTION_WITH_STATUS_DIFFERENT_OF_APPROVED`	Quando o cancelamento é chamado mas o status do pagamento é diferente de aprovado.
`FAIL_TO_SAVE_LOCAL`	Quando ocorrer uma falha no salvamento local. A transação é cancelada com sucesso, porém houve erro para atualizar o status (haverá tentativa de atualizar localmente na próxima consulta).
`DUPLICATE_CALL_SDK`	Bloqueio de chamadas duplicadas. Quando uma chamada está em andamento, novas chamadas são temporariamente bloqueadas para evitar duplicidade. Assim que a chamada atual for concluída, o sistema libera a execução de novas chamadas.