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.

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:

Exceptions de Inicialização

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.

Exceptions com tela

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

Exceptions	Descrição
`ProblemToInitializerException`	Falha genérica durante a inicialização (servidor/regras de negócio).
`DeviceIncompatibleException`	Caso específico: Ocorre apenas quando o motivo é `DEVICE_WITH_VERSION_OS_INCOMPATIBLE`, ou seja, o sistema Android do dispositivo está abaixo do mínimo suportado. Para os demais motivos do enum `DeviceIncompatibleEnum`, consulte a seção Exceptions sem tela.

Exceptions sem tela

Essas exceptions não exibem interface automaticamente.

Exceptions	Descrição
`DeviceIncompatibleException`	Caso específico: Quando o dispositivo não é compatível com as regras do SDK (Root, Emulador, Modo Desenvolvedor ativo, Ausência/Problema de NFC, SO < Android 11 ou Hook detectado). Segue abaixo um enum do que poderá ser retornado pela exception. Para o motivo `DEVICE_WITH_VERSION_OS_INCOMPATIBLE`, o SDK exibe uma tela de erro ao usuário.
`CheckIsTerminalActiveException`	Falha ao consultar ou registrar o terminal transacional.
`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.

enum class DeviceIncompatibleEnum {
    DEVICE_IS_EMULATOR,
    DEVICE_IS_ROOT,
    DEVICE_IS_DEV_MODE,
    DEVICE_PROBLEM_WITH_NFC,
    DEVICE_WITH_VERSION_OS_INCOMPATIBLE,
    DEVICE_WITH_HOOK_DETECTED
}

Callbacks de erro transacional (`ErrorsPaymentEnum`)

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, ou com um merchantOrderId inválido, o SDK retorna um erro em onPaymentFailure. Consulte a seção 5. Callback do transacional para ver os códigos de erro.

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.
`PROBLEM_TO_INIT_TERMINAL`	Falha de ativação ou comunicação com o leitor NFC.
`PROBLEM_TO_PARTIAL_PAYMENT`	Resposta de pagamento parcial, que o SDK não suporta.
`TRANSACTION_BIGGER_OR_EQUALS_THEN_45_DAYS`	Ocorre quando é solicitado o cancelamento de uma transação com mais de 44 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.

Exceptions de Inicialização

Exceptions com tela

Exceptions sem tela

Callbacks de erro transacional (ErrorsPaymentEnum)

Callbacks com tela

Callback sem tela

Callbacks de erro transacional (`ErrorsPaymentEnum`)