Getnet DocsGetnet Docs

Arquitetura

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Esta página explica os componentes arquitetônicos e o fluxo de comunicação que alimentam a integração do Get Tap on Phone (App2App). Entender esta arquitetura ajuda você a projetar uma integração robusta entre seu aplicativo Android, o aplicativo Tap on Phone e seus sistemas de backend.

Os Componentes Principais

A integração App2App depende de quatro componentes distintos trabalhando juntos para autorizar e processar um pagamento de forma segura.

  1. Seu Aplicativo (Client App) Este é o seu aplicativo Android de Registro de Caixa Eletrônico (ECR) ou Ponto de Venda (POS). Ele atua como a interface principal para o lojista. Ele gerencia a sessão do usuário, o carrinho de compras e inicia solicitações de pagamento ou inicialização.
  2. Aplicativo Tap on Phone (Whitelabel App) Este é o aplicativo de pagamento seguro instalado no mesmo dispositivo Android. Ele permanece inativo até que seu aplicativo o chame. Uma vez invocado, ele assume o controle da tela para gerenciar tarefas seguras, como leitura de cartão NFC e inserção de PIN, e então retorna o resultado para o seu aplicativo.
  3. Backend do Tap on Phone Esta plataforma baseada em nuvem roteia os dados da transação para as redes adquirentes e gerencia a configuração do terminal móvel. Crucialmente, ela intercepta as solicitações do aplicativo Tap on Phone e pede permissão ao seu backend para prosseguir.
  4. Seu Backend (Client Backend) Esta é a infraestrutura de servidor da sua organização. Ela hospeda o endpoint de autorização de Single Sign-On (SSO). Ela valida a sessão do usuário e aprova ou nega operações sensíveis com base nas permissões do lojista.

O Fluxo de Comunicação

Como o aplicativo Tap on Phone opera de forma segura e independente, ele depende do seu aplicativo e do seu backend para autenticar o usuário.

Aqui está a sequência de eventos quando seu aplicativo solicita uma operação protegida (como inicializar o terminal ou processar um estorno):

  1. Iniciação: Seu aplicativo envia uma solicitação para o aplicativo Tap on Phone no dispositivo local, passando o userId, merchantId e um userToken seguro.
  2. Solicitação de Validação: O aplicativo Tap on Phone encaminha esta solicitação para o Backend do Tap on Phone.
  3. Solicitação de Permissão de SSO: O Backend do Tap on Phone usa o ClientID para localizar seu endpoint de SSO específico. Ele envia uma solicitação de API para o seu backend contendo o userToken e a operação solicitada.
  4. Autorização: Seu backend verifica o token e as permissões do usuário, retornando uma resposta HTTP 200 OK se aprovado.
  5. Execução: O Backend do Tap on Phone sinaliza para o aplicativo Tap on Phone prosseguir com a operação.
  6. Conclusão: O aplicativo Tap on Phone executa a operação (ex: configurar o terminal ou solicitar um cartão) e retorna o resultado final para o seu aplicativo.

Padrões de Comunicação do Android

Para facilitar a comunicação local entre seu aplicativo e o aplicativo Tap on Phone, a integração usa mecânicas padrão do Android.

Intents e a Activity Result API

Para operações síncronas que exigem uma interface de usuário — como inicializar o aplicativo ou processar um pagamento — você usa Android Intents.

Para receber o resultado desses intents, você deve usar as modernas Activity Result APIs (introduzidas no AndroidX Activity 1.2.0 e Fragment 1.3.0).

  • Você inicia o intent usando um launcher registrado.
  • O aplicativo Tap on Phone processa a solicitação e finaliza sua activity.
  • Seu callback registrado recebe um RESULT_OK (sucesso) ou RESULT_CANCELED (falha ou cancelamento pelo usuário), junto com um Intent contendo os dados detalhados da resposta (extras).

Broadcast Receivers

Para operações assíncronas ou tarefas em segundo plano que não requerem uma interface de usuário imediata, a integração usa Broadcasts.

Você usa broadcasts para:

  • Verificar o Status do POS: Verificar se o terminal está totalmente inicializado antes de tentar uma transação.
  • Acionar Atestações: Forçar uma verificação de segurança em segundo plano para evitar atrasos durante o fluxo de checkout.
  • Recuperar o Status da Transação: Consultar o status de um UUID de transação específico se o seu aplicativo falhou (crashed) ou perdeu o Activity Result original.
  • Redefinir o POS: Limpar a sessão do usuário atual e a configuração.

Quando você envia uma solicitação de broadcast para o aplicativo Tap on Phone, você pode fornecer uma string ResponseAction personalizada. O aplicativo Tap on Phone realiza a ação solicitada em segundo plano e emite um broadcast de resposta usando exatamente essa string, permitindo que seu aplicativo escute o resultado.