> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/first-tech-ttp-sdk-pt/area-do-desenvolvedor/solucao-de-problemas-durante-testes-e-producao.md). # Solução de Problemas Durante Testes e Produção Os erros listados abaixo geralmente ocorrem durante o processo de Prova de Conceito (POC), nas tentativas iniciais de integração ou na implantação do SDK em ambientes de homologação e produção. Para cada estágio do processo de transação, apresentaremos os erros mais comuns, juntamente com um caminho estruturado de solução de problemas e as verificações necessárias para cada situação. Esta abordagem sistemática facilita a identificação e resolução de problemas, garantindo uma transição mais suave entre as fases de desenvolvimento, homologação e produção. ### Como Ativar o Terminal A ativação do terminal, conforme discutido nas seções anteriores, é uma etapa crítica que requer o cumprimento de pré-requisitos específicos no ambiente de produção do sistema operacional Android. Durante o processo de criação do terminal, se esses pré-requisitos não forem atendidos, o SDK retornará um erro da classe TerminalInitializingErrorViewData, com a descrição DEVICE\_STATE\_FAILED, indicando que a ativação não foi bem-sucedida. Abaixo, descrevemos as principais razões que podem causar essa falha. #### **1. P**ermissões Necessárias para Operar o SDK Dentro do Aplicativo Inicialmente, é necessário verificar se o aplicativo tem acesso às seguintes permissões do Android:
FeaturePermission
NFCandroid.Manifest.permission.NFC
Vibrateandroid.Manifest.permission.VIBRATE
Internetandroid.permission.INTERNET
Network Stateandroid.permission.ACCESS_NETWORK_STATE
Access Notification Policyandroid.permission.ACCESS_NOTIFICATION_POLICY
Accurate Locationandroid.permission.ACCESS_FINE_LOCATION
Approximate Locationandroid.permission.ACCESS_COARSE_LOCATION
Para verificar se as permissões foram solicitadas, abra o arquivo AndroidManifest.xml, que deve ser acessado pelo desenvolvedor do projeto Android. Neste arquivo, algumas permissões são configuradas automaticamente, enquanto outras precisam ser declaradas explicitamente de acordo com a política de segurança do Android. A lém disso, você pode solicitar uma captura de tela do desenvolvedor para confirmar as permissões diretamente no dispositivo.

Figure 23: Screenshot of the AndroidManifest.xml File from a React Native Project Using the TTP SDK

Mesmo que as permissões estejam implementadas no aplicativo, no ambiente de produção (quando o app é baixado da loja), o Android solicitará a confirmação do usuário para acessar determinados recursos, como a câmera ou o microfone. \ É essencial verificar se o aplicativo fez essas solicitações e se o usuário concedeu permissão para esses recursos. \ Se houver dúvidas sobre a concessão de permissões, recomende reinstalar o aplicativo. Isso permitirá que as etapas necessárias sejam repetidas, garantindo que permissões, como microfone e NFC, sejam solicitadas e concedidas no momento apropriado. *** 2. Modo Root se o superusuário estiver conectado e habilitado no Android, o SDK não conseguirá completar a fase de criação do terminal, seja em homologação ou produção. Para verificar se o dispositivo está em modo root, siga um processo semelhante ao descrito na Seção 2 para coleta de logs: 1. Peça ao desenvolvedor do aplicativo para configurar as variantes de compilação no Android Studio para o ambiente de homologação (hml) enquanto usa o SDK de homologação. 2. Com o projeto aberto no Android Studio, acesse a janela do console pressionando Alt + F12.. * Se o desenvolvedor não estiver familiarizado com variantes de compilação, recomende a leitura da Seção 4: Preparação do Ambiente para Começar. 3. Conecte o dispositivo móvel ao computador usando um cabo USB e digite o seguinte comando: ``` adb shell ``` Em seguida, verifique se é possível acessar o superusuário do Android no dispositivo móvel: ``` su ``` Se o dispositivo solicitar permissão ou mudar para o modo superusuário (root), isso indica que o acesso root está habilitado. Por outro lado, se o comando retornar uma mensagem como "comando não encontrado", o dispositivo não possui acesso root. *** 3. Modo Desenvolvedor O modo desenvolvedor é permitido apenas para o SDK de staging, mas não para o SDK de produção. Se você estiver em produção e encontrar o erro DEVICE\_STATE\_FAILURE durante a etapa de criação do terminal, você deve desativar o modo desenvolvedor no dispositivo Android onde o aplicativo está instalado. #### Para desativar o modo desenvolvedor, siga estas etapas: 1. Abra o menu Configurações no Android e procure por Opções de Desenvolvedor ou Opções de Programador, dependendo do modelo do dispositivo e da versão do Android. 2. Se este submenu não for encontrado, significa que o modo desenvolvedor nunca foi ativado.. #### Para confirmar se o modo desenvolvedor está ativo: 1. á para o submenu Sobre o Telefone no menu Configurações. 2. Toque sete vezes no campo Número da Versão. Após isso, o Android exibirá uma mensagem confirmando que as Opções de Desenvolvedor foram ativadas. 3. Abra o menu Opções de Desenvolvedor recém-criado e desative o modo desenvolvedor. Esta ação garantirá que o dispositivo esteja configurado corretamente para o ambiente de produção. *** 4. **Potentially Malicious Applications** Outro motivo para o erro DEVICE\_STATE\_FAILURE durante a fase de criação do terminal é a presença de aplicativos que podem monitorar a troca de dados entre apps, habilitar o modo root ou coletar dados sensíveis, comprometendo a segurança dos dados de pagamento lidos via NFC. Esta verificação ocorre tanto no modo de staging quanto no modo de produção. Abaixo está uma lista de aplicativos conhecidos que podem causar este erro (não limitados a estes, pois podem existir variações com efeitos semelhantes): * Magisk * Frida * Cydia Substrate * SuperSU * Xposed \ Se qualquer um desses aplicativos for encontrado no dispositivo, recomendamos fortemente realizar uma restauração de fábrica. Isso garante que os testes sejam reiniciados em um ambiente limpo, evitando possíveis interferências residuais na integridade do sistema operacional, mesmo após esses aplicativos terem sido removidos. //Another reason for the **`DEVICE_STATE_FAILURE`** error during the **terminal creation phase** is the presence of **applications that can monitor data exchange between apps, enable root mode, or collect sensitive data**, compromising the **security of payment data read via NFC**. This verification takes place in **both staging and production modes**. Below is a list of **known applications** that may cause this error (**not limited to these, as variations with similar effects may exist**): * Magisk * Frida * Cydia Substrate * SuperSU * Xposed If any of these applications are found on the device, we **strongly recommend** performing a **factory reset**. This ensures that **tests are restarted in a clean environment**, preventing **potential residual interference** with the integrity of the **operating system**, even after these applications have been removed. *** 5. Apps Instalados Fora da Loja No ambiente de produção, aplicativos instalados fora da loja oficial podem ser sinalizados pelo Play Integrity, marcando o dispositivo como inseguro para transações. Se houver suspeita de tais aplicativos, desinstale-os e tente criar o terminal novamente. O SDK realiza verificações de segurança continuamente para garantir que o dispositivo seja sempre classificado como seguro, mantendo a integridade e segurança das transações. Outros problemas menos complexos retornados pela visualização TerminalInitializingErrorViewData durante a fase de inicialização podem incluir: | Error Returned by the View | Cause | Solution | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UNSUPPORTED\_ANDROID\_OS\_VERSION |

A versão do Android no dispositivo não é suportada pelo SDK.

| Solicite uma captura de tela da versão do Android no dispositivo e verifique se ela atende às especificações mínimas descritas neste documento. Adicionalmente, se possível, oriente o cliente a atualizar a versão do Android. Esta opção é mais viável para modelos recentes ou dispositivos que foram restaurados para configurações de fábrica. Se o cliente não souber como encontrar esta opção, peça o modelo do dispositivo e forneça instruções. Embora nomes e descrições possam variar, a versão do Android geralmente é encontrada no submenu Sobre no aplicativo de Configurações do dispositivo. | | NETWORK\_CONNECTION\_ERROR | O dispositivo não tem acesso à internet durante o processo de criação do terminal. |

Peça ao portador do dispositivo para abrir um navegador e acessar qualquer site ou usar uma ferramenta de teste de velocidade para verificar a qualidade da conexão. | |
Idealmente, redes de alta velocidade e baixa latência devem sempre ser utilizadas, preferencialmente conectando-se a uma rede Wi-Fi confiável sempre que possível.

| | | | TERMINAL\_NOT\_INITIALISED\_YET |

Falha interna do SDK.

|

Esta é uma falha interna do produto que atualmente não possui procedimento de mitigação. | |
Recomenda-se abrir um ticket com o First Tech, anexando os logs coletados para investigação imediata.

| | | | INTERNAL\_ERROR | Erro interno genérico do SDK./ |

Esta é uma falha interna do produto que atualmente não possui procedimento de mitigação disponível. | |
O erro inclui detalhes adicionais no campo de exceção, que serão analisados pela equipe do First Tech. | | | |
Recomenda-se abrir um ticket com o First Tech, anexando os logs coletados para investigação imediata.

| | | ### Como Ativar a Sessão Após concluir com sucesso o processo de verificação de integridade do terminal, o próximo passo é a criação da sessão. Nesta etapa, o aplicativo é validado com base em suas credenciais e certificados no Google Play. Se nenhum problema for detectado, o SDK prosseguirá para o processo de solicitação do cartão. Os problemas mais comuns nesta fase geralmente se enquadram em duas categorias: 1. Falha na Recuperação de Dados do Aplicativo da Loja: * #### O desenvolvedor deve garantir que todas as informações necessárias estejam disponíveis e atualizadas. 2. #### Atualização de Versão Sem Comunicação: * #### Quando uma nova versão do aplicativo é publicada na loja, o desenvolvedor deve solicitar oficialmente a liberação desta versão em produção com o First Tech. * #### Quando uma nova versão do aplicativo é publicada na loja, o desenvolvedor deve solicitar oficialmente a liberação desta versão em produção com o First Tech. Este processo garante o controle autorizado de uso do SDK nos dispositivos dos clientes. #### Para liberar a versão, um ticket de suporte deve ser aberto com os seguintes três detalhes essenciais\:/**:** * SHA-256 do certificado (fingerprint) * Nome do Pacote (Package Name) * Código da Versão (Version Code) SHA-256 - Impressão Digital do Certificado de Assinatura do Aplicativo \ O SHA-256 é uma impressão digital única gerada pelo certificado de assinatura do aplicativo no Google Play. É público e usado para autenticar o aplicativo, garantindo sua exclusividade. O First Tech requer esses dados apenas na primeira vez que o aplicativo é distribuído na loja. O processo de geração do SHA-256 é gerenciado pelo Google e envolve várias etapas, que podem ser encontradas na documentação oficial. Para fornecer o valor necessário, siga estas etapas: * Acesse o menu de configurações do Google Play Console (mais detalhes play.google.com). * Navegue até Configuração > Integridade do aplicativo > Certificado de chave de assinatura do aplicativo > Impressão digital do certificado SHA-256.. * Copie o valor hexadecimal exibido e envie-o para o First Tech.. Este passo é essencial para validar a integração e permitir o uso autorizado do SDK..

Figure 24: App Integrity Configuration Screen within the Google Portal where the SHA-256 Certificate Fingerprint can be viewed

Exemplo de SHA-256 certificate Fingerprint ``` BD : 92 : 64 : B0 : 1A : B9 : 08 : 08 : FC : FE : 7F : 94 : B2 ``` Package Name - Nome de Identificação Único do Aplicativo Android O Package Name é o identificador único para um aplicativo Android, usado para diferenciá-lo de outros apps instalados no dispositivo. Esta convenção de nomenclatura evita conflitos entre aplicativos e é essencial tanto para a funcionalidade do sistema quanto para testes de software, sejam manuais ou automatizados. Embora o Package Name seja atribuído automaticamente quando o app é enviado para o Android, ele pode ser alterado se necessário. O formato geralmente segue o padrão: \ com.seudominio.nomeapp. Por exemplo, se o site do desenvolvedor é meusite.com e o app é chamado MeuApp, o Package Name poderia ser com.meusite.meuapp. Como localizar o Package Name: Peça ao desenvolvedor para acessar o arquivo build.gradle do módulo do app. Dentro do objeto defaultConfig, localize a variável applicationId, que conterá o Package Name. Este valor será único para cada app suportado. Esta informação é essencial para a correta integração com o SDK e para identificar com precisão o app na loja e nos dispositivos. #### **//Package Name - Unique Identification Name of the Android Application** The **Package Name** is the **unique identifier** for an Android application, used to differentiate it from other apps installed on the device. This **naming convention** prevents conflicts between applications and is essential for both **system functionality** and **software testing**, whether manual or automated. Although the **Package Name** is automatically assigned when the app is submitted to Android, it can be **changed if necessary**. The format typically follows the pattern:\ **com.yourdomain.appname**. For example, if the developer's website is **meusite.com** and the app is called **MeuApp**, the **Package Name** could be **com.meusite.meuapp**. #### **How to locate the Package Name:** Ask the developer to access the **build.gradle** file of the app module. Inside the **defaultConfig** object, locate the **applicationId** variable, which will contain the **Package Name**. This value will be **unique** for each supported app. This information is **essential** for the **correct integration with the SDK** and for **accurately identifying the app** in the store and on devices.

Figure 25: Example app with the Build.Gradle file open and the applicationId variable highlighted

Version Codes - Identificação da Versão do Aplicativo \ O Version Code representa a versão do aplicativo e é usado pelo First Tech para identificar quais versões do produto são válidas para o SDK Tap to Phone durante a fase de criação da sessão. Este parâmetro é cumulativo, o que significa que todas as versões válidas devem ser enviadas, permitindo que múltiplas versões estejam ativas simultaneamente. Notas Importantes sobre o Version Code: Follow the same procedure used to locate the **Package Name**, but look for the **versionCode** variable inside the **defaultConfig** object in the **build.gradle** file of the app module. Ensuring the correct submission of this information is **essential for secure and efficient operation**. #### **//Version Codes - Application Version Identification** The **Version Code** represents the version of the application and is used by **First Tech** to identify which product versions are valid for the **Tap to Phone SDK** during the **session creation phase**. This parameter is **cumulative**, meaning all valid versions must be sent, allowing multiple versions to be active simultaneously. #### **Important Notes about Version Code:** * The list of valid versions must include **all corresponding strings**, as only the **latest version** provided will be considered as the reference. * Clients can submit **future versions**, allowing app updates to be performed without the need to immediately open new support tickets. * It is a good practice to **notify First Tech** when older versions are no longer valid. This prevents transactions on those versions and forces end users to update the app, ensuring **greater security and compatibility**. **How to Identify the Version Code:** Follow the same procedure used to locate the **Package Name**, but look for the **versionCode** variable inside the **defaultConfig** object in the **build.gradle** file of the app module. Ensuring the correct submission of this information is **essential for secure and efficient operation**.

Figure 26: Example React Native app with the Build.Gradle file open and the versionCode variable displayed

**Example of Sending Data by Email to Enable Version in Production** > Dear First Tech Team, good morning! > > Could you please enable our app in production?\ > Here are the details: > > **SHA-256 of the app on the store:** BD : 92 : 64 : B0 : 1A : B9 : 08 : 08 : FC : FE : 7F : 94 : B2\ > **Package Name of the app:** com.notke.paymentapp\ > **Version Codes:** 20, 21, 22, 23, 24, and 25 Para versões do SDK Tap to Phone acima de 1.0.20, o processo de registro do aplicativo em produção retornará ao desenvolvedor três campos que devem ser usados exclusivamente no ambiente de produção. Esses campos devem ser adicionados na chamada do SDK dentro do método StartPayment. As variáveis são: {% code lineNumbers="true" %} ``` Client Id Cliente Secret Scope ``` {% endcode %} Essas variáveis devem ser incluídas na chamada junto com o CPF, CNPJ, ID do Cliente e outras informações que o SDK já solicita dos clientes. Elas são essenciais para completar o processo de criação da sessão e permitir a progressão para as etapas seguintes. Detalhes adicionais sobre essas variáveis podem ser encontrados nas especificações técnicas destinadas ao desenvolvedor. Se esta etapa não for realizada corretamente, a view TerminalSessionCreatedErrorViewData exibirá o erro DEVICE\_STATE\_FAILURE, que é o problema mais comum encontrado durante a fase de ativação da sessão. Outros problemas menores e mais raros também podem ocorrer durante o processo de ativação da sessão. Abaixo, listamos esses problemas junto com suas possíveis soluções: | Error Returned by the View | Cause | Solution | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | INTERNAL\_ERROR | Erro Interno Genérico do SDK |

Este é uma falha interna do produto que atualmente não possui procedimento de mitigação disponível.

O erro contém detalhes adicionais no campo exception, que serão analisados pela equipe do First Tech. Recomenda-se abrir um ticket de suporte com o First Tech, anexando os logs coletados, para possibilitar uma investigação imediata.

| | DEACTIVATED | O terminal foi desativado durante o processo de criação da sessão. | "Isso pode ocorrer devido a uma ação manual realizada pela adquirente, pela First Tech em casos de suspeita de fraude, ou a pedido do estabelecimento comercial. O cliente deve reiniciar o aplicativo para tentar criar um novo terminal. Se o erro persistir, pode haver um problema com o SDK, e é recomendado abrir um chamado de suporte para que a equipe da First Tech investigue a causa. | | CONFIGURATION\_VALIDATION\_HASH\_FAILURE | O arquivo de configuração EMV (conhecido como EMV Config) foi invalidado por razões de segurança ou está sendo atualizado pela equipe da First Tech para todos os usuários do aplicativo do cliente. | O arquivo de configuração EMV define os tipos de produtos e cartões reconhecidos durante a fase de leitura TTP. Sua atualização é verificada automaticamente a cada nova transação e, se necessário, será realizada nesse momento. Oriente o cliente a aguardar alguns minutos e tentar a transação novamente. Se o erro persistir, abra um chamado de suporte para que a equipe da First Tech investigue o problema imediatamente. | | NFC\_ERROR | O NFC foi solicitado por outro aplicativo para uso ou foi desativado no Android. |

Tradução

Peça ao cliente para fechar todos os aplicativos, verificar se o NFC está habilitado no dispositivo Android e confirmar se o dispositivo suporta NFC. Depois que esses problemas forem resolvidos, tente realizar a operação novamente.

| | NETWORK\_ERROR |

Tradução

O aplicativo não tem acesso à internet ou houve uma falha no servidor de back-end.

|

Tradução

Oriente o portador do dispositivo a abrir um navegador e acessar qualquer site ou usar uma ferramenta de teste de velocidade para verificar a qualidade da conexão. | |
Sempre que possível, use redes de alta velocidade e baixa latência, preferencialmente conectando-se a uma rede Wi-Fi confiável. | | | |
Se o problema persistir mesmo com conectividade à internet, é provável que o problema esteja no back-end. Nesse caso, é recomendado abrir um chamado de suporte para que a First Tech investigue a causa.

| | | ### Aproximação do Cartão e Início da Transação//**Bringing the Card Close and Starting the Transaction** Se o terminal e a sessão forem ativados com sucesso, o dispositivo estará pronto para realizar a aproximação do cartão. Para evitar problemas, é recomendado consultar a Seção 7: Solução de Problemas Durante Testes e Produção para obter as melhores práticas sobre o manuseio do dispositivo, garantindo que o aplicativo não experimente tempos limite de leitura causados por posicionamento inadequado do cartão ou dificuldades com o leitor NFC dentro do tempo permitido para a operação. Além disso, outros fatores importantes incluem: * Rede estável: Garanta que a conexão seja confiável para evitar interrupções. * Cartão válido: Use um cartão ativo, não vencido, com saldo ou limite disponível, e com a função de pagamento por aproximação ativada.. * Modo correto do cartão: Alguns bancos digitais têm funções de débito e crédito invertidas. Por exemplo, usar um cartão de débito como crédito pode resultar no erro "Sem seletor de aplicação para o cartão". Outro ponto de atenção é durante a fase de programação. Certifique-se de que os enums PaymentType estejam configurados corretamente, pois valores invertidos podem levar a falhas semelhantes. Uma situação mais rara, mas possível, é a dificuldade na leitura de cartões mais novos ou menos comuns devido à ausência de IDs de Aplicação no banco de dados do SDK. Este problema também pode gerar o erro "Sem seletor de aplicação para o cartão." Neste caso, será necessário abrir um chamado para que a First Tech, em colaboração com a adquirente, possa revisar as tabelas responsáveis pelo reconhecimento do cartão e implementar as atualizações necessárias. O SDK será atualizado automaticamente, sem necessidade de ação do desenvolvedor, na próxima tentativa de transação. Neste ponto, os erros exibidos na view TerminalPaymentErrorViewData podem ter duas origens distintas: * Erros relacionados ao SDK * Erros relacionados à autorização. Aqui estão os erros comuns relacionados ao SDK e suas possíveis soluções: | Error Returned by the View | Cause | Solution | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NETWORK\_CONNECTION\_ERROR |

Tradução

O dispositivo não tem acesso à internet durante o processo de criação do terminal.

|

Tradução

Peça ao portador do dispositivo para abrir um navegador e acessar qualquer site ou usar uma ferramenta de teste de velocidade para verificar a qualidade da conexão. | |
Idealmente, sempre use redes de alta velocidade e baixa latência, preferencialmente conectando-se a uma rede Wi-Fi confiável sempre que possível.

| | | | MICROPHONE\_USAGE\_DETECTED |

Tradução

Outro aplicativo ou processo está usando o hardware do microfone.

|

Tradução

O microfone precisa ser bloqueado durante o uso de aplicativos que potencialmente possam estar usando o recurso. Feche todos os programas e reabra o aplicativo para uma nova tentativa.

| |

CAMERA\_USAGE\_DETECTED

EXTERNAL\_CAMERA\_DETECTED

|

Tradução

Outro aplicativo ou processo está usando o hardware da câmera frontal ou externa do telefone.

|

Tradução

As câmeras precisam ser bloqueadas durante o uso de aplicativos que potencialmente possam estar usando o recurso. Feche todos os programas e reabra o aplicativo para uma nova tentativa.

| | TOTAL\_ELAPSED\_TIMEOUT |

Tradução

O tempo total de operação desde a leitura do cartão até a aprovação da transação foi excedido.

|

Tradução

O SDK está configurado para um tempo total de transação de 60 segundos nestas etapas, e este tempo é definido diretamente pela First Tech nos arquivos de Configuração EMV, que são verificados e atualizados a cada transação. Este é um tempo mais que razoável para completar todo o processo. Este erro aparece quando não houve interação do cliente para aproximar o cartão, ou o tempo de autorização da transação está muito longo. | |
Recomendamos abrir um chamado de suporte com a First Tech, incluindo uma gravação em vídeo do comportamento do aplicativo para melhor entender a causa.

| | | | DISCOVERY\_TIMEOUT |

Tradução

O tempo designado para a leitura do cartão expirou.//The designated time for card reading has expired.

|

Este problema pode ser causado por uma questão no manuseio do dispositivo ou dificuldade na leitura do cartão, que pode estar danificado ou inválido. | |
Recomendamos o seguinte: | | | |
Teste o mesmo aplicativo em outro dispositivo. | | | |
Teste o mesmo dispositivo com um cartão diferente, preferencialmente da mesma bandeira e no mesmo modo (débito/crédito).//This problem may be caused by an issue with device handling or difficulty in reading the card, which may be damaged or invalid.

We recommend the following:

  1. Test the same app on another device.
  2. Test the same device with a different card, preferably from the same network and in the same mode (debit/credit).
| | | |

PIN\_ENTRY\_ACCUMULATED\_TIMEOUT

PIN\_ENTRY\_TIMEOUT

| O tempo para exibição da tela de PIN e inserção da senha expirou. |

A tela de PIN é apresentada através de um processo criptográfico para sua geração entre o SDK e o back-end. Além deste tempo, há também o tempo que o usuário leva para inserir o PIN do cartão. A combinação destes dois tempos pode causar este erro. | |
Teste a transação novamente para verificar se o comportamento persiste. Se o problema ocorrer a cada duas ou três interações, pode ser necessário aumentar o tempo para inserção do PIN ou pode haver um erro criptográfico no back-end. Neste caso, abra um chamado de suporte para que a First Tech investigue.

| | | | AUTHORIZATION\_IN\_PROGRESS\_TIMEOUT |

A transação não pode ser autorizada dentro do tempo máximo definido para autorização da transação.

|

Existe um atraso maior que o esperado entre o back-end do SDK e a Adquirente. | |
Se o cliente tiver acesso ao painel com suas transações, é útil verificar se a transação foi registrada e está aguardando confirmação. | | | |
Se não houver visibilidade dentro do contexto da adquirente, é provável que tenha ocorrido um problema no back-end do SDK no envio desta mensagem. Neste caso, abra um chamado com a First Tech, incluindo as evidências da transação que estão disponíveis.

| | | | INTERNAL\_ERROR | Erro interno genérico do SDK. |

Este é um erro interno do produto que atualmente não possui procedimento de mitigação disponível. | |
O erro contém detalhes adicionais no campo de exceção, que serão analisados pela equipe da First Tech. | | | |
Recomenda-se abrir um chamado de suporte com a First Tech, anexando os logs coletados, para possibilitar a investigação imediata.

| | | | HOST\_CALLBACK\_ERROR | O SDK não está recebendo a resposta de transação aprovada ou negada do back-end. |

A Adquirente e a First Tech precisam verificar o problema em conjunto. | |
Se a transação realmente estiver aguardando aprovação e não houver resposta, o problema precisa ser investigado com a adquirente através da abertura de um chamado específico. | | | |
Se a transação puder ser rastreada no console da adquirente e já tiver um status confirmado ou negado, então é necessário abrir um chamado com a First Tech.

| | | | PIN\_PAD\_OBSCURED\_ERROR | Um aplicativo com permissão para "aparecer sobre outros aplicativos" interferiu na tela de entrada do PIN quando ela foi exibida. | Encontre o aplicativo com este comportamento e desinstale-o ou remova temporariamente essa permissão. Em seguida, feche o aplicativo e abra-o novamente para realizar a transação. | | PIN\_PAD\_DETACHED\_ERROR | O processo da tela de PIN foi fechado manualmente no Android. | Feche e reabra o aplicativo, depois repita a transação. Se o erro persistir, tente identificar aplicativos que possam estar causando esse comportamento. Se não for o caso, abra um chamado com a First Tech para relatar o problema.. | | PIN\_PAD\_LAUNCH\_TIMEOUT | A tela de PIN demorou mais de 2 segundos para ser exibida./an 2 seconds to display. | Tente uma nova transação. Se o problema persistir, abra um chamado com a First Tech para relatar o problema. | | NFC\_ERROR | O NFC foi solicitado por outro aplicativo para uso ou foi desativado no Android | Ask the customer to **close all applications**, check if **NFC is enabled** on the Android device, and confirm if the device **supports NFC**. Once these issues are resolved, try performing the operation again. | A transação também pode ser negada devido a falhas de autorização com a adquirente. Isso está relacionado a falhas no cartão, regras de prevenção à fraude, problemas de senha e disponibilidade do ecossistema de pagamento: serviços de autorização das redes de cartões, disponibilidade da adquirente e outros. Os erros retornados estão alinhados com a Normativa 21 da ABECS, que pode ser encontrada para problemas com a adquirente. É importante que esses retornos sejam exibidos aos clientes, imitando o comportamento de um POS comum, e fornecendo visibilidade sobre erros que podem ou não ser repetidos. Isso ajuda a proteger o comerciante de ser cobrado por taxas pelo uso indevido de tentativas de autorização pela adquirente através das redes de cartões (Visa, Mastercard e Elo). Para verificar esses erros, além da resposta nas visualizações TerminalPaymentSuccessViewData e TerminalPaymentErrorViewData, respectivamente para aprovações e negações de transações, o campo meta retornará um objeto com os detalhes dessa transação do lado da adquirente, indicando o processamento da autorização. Exemplo do Campo Meta Preenchido se a Transação for Negada ```json { "providerResponse": { "mti": "2210", "processingCode": "002000", "amount": "9862000000000041", "transmitionDateTime": "20250123133118", "stan": "842379", "transactionDateTime": "20250123133117", "authorizerId": "16", "muxipayResponseCode": "8001", "authorizerResponseCode": "05", "terminalId": "00000007", "merchantId": "00595154000173", "emvTags": "8a023035", "customerId": "FIRSTTECH", "displayCustomerMessage": "TRANSACAO NEGADA\nCONTATE A\nCENTRAL DO SEU\nCARTAO", "trackingNumber": "020001419451", "muxipayUniversalId": "00ad54c01b8d064501e1ec6b34df8eac", "initializationRequired": "10", "hostStan": "000725", "error": { "code": "invalid operation", "message": "Error occurred on authorize message", "metadata": { "acquirer": "rejected", "authorizer": "do_not_honour" } } }, "error": { "type": "acquirer", "code": "invalid operation", "message": "Error occurred on authorize message", "metadata": { "acquirer": "rejected", "authorizer": "do_not_honour" } }, "status": "COMPLETED_WITH_ERROR", "reason": "OPERATION_ERROR" } ``` Exemplo do Campo Meta Preenchido se a Transação for Autorizada ```json { "mti": "2210", "muxipayUniversalId": "67bea6f89c319638f35e2b9273739df5", "receipt": { "merchant": { "message": "DOCK - Via Loja\n\nFIRST CUSTOMER\nCNPJ: 10179118609\nTID: 020001419130\n\n*** *** **** 5461\nMASTERCARD\nAID: A0000000041010\n23/01/25 13:04\nCV: 855614\nValor: R$ 0,23\nForma de pagamento: Crédito\nÀ vista\nTerm: 00000486\n\nDADOS ORIGINAIS DA VENDA\nValor: R$ 0,23\nTerm: 00000486\nTransação autorizada pelo emissor\n" }, "customer": { "message": "DOCK - Via Cliente\n\nFIRST CUSTOMER\nCNPJ: 10179118609\nTID: 020001419130\n\n*** *** **** 5461\nMASTERCARD\nAID: A0000000041010\n23/01/25 13:04\nCV: 855614\nValor: R$ 0,23\nForma de pagamento: Crédito\nÀ vista\nTerm: 00000486\n\nDADOS ORIGINAIS DA VENDA\nValor: R$ 0,23\nTerm: 00000486\nTransação autorizada pelo emissor\n" } }, "displayMessages": { "customer": "TRANSACAO APROVADA" }, "providerResponse": { "mti": "2210", "processingCode": "003000", "amount": "9862000000000023", "transmitionDateTime": "20250123130431", "stan": "855614", "transactionDateTime": "20250123130429", "authorizerId": "16", "retrievalReferenceNumber": "020001419130", "authorizationCode": "043063", "muxipayResponseCode": "8000", "authorizerResponseCode": "00", "terminalId": "00000486", "merchantId": "10179118609", "emvTags": "8a023030", "customerId": "BIPPAGAMENTOS", "displayCustomerMessage": "TRANSACAO APROVADA", "trackingNumber": "020001419130", "muxipayUniversalId": "67bea6f89c319638f35e2b9273739df5", "initializationRequired": "10", "hostStan": "000012" }, "status": "COMPLETED_SUCCESSFULLY", "reason": "COMPLETED_SUCCESSFULLY" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ftcoders.first-tech.com/first-tech-ttp-sdk-pt/area-do-desenvolvedor/solucao-de-problemas-durante-testes-e-producao.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.