Getnet DocsGetnet Docs

Ciclo de Vida da Transação

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

Entender o ciclo de vida completo da transação garante que você implemente um fluxo de pagamento robusto e confiável. Esta página explica a jornada de ponta a ponta de um pagamento Tap on Phone, desde a verificação do status inicial do terminal até a determinação do resultado final da transação.

O Fluxo de Pagamento Padrão

Uma transação de pagamento bem-sucedida geralmente segue uma sequência padrão de eventos entre o seu aplicativo cliente e o aplicativo Tap on Phone.

  1. Verificação de Status (Opcional, mas Recomendado): Antes de iniciar um pagamento, seu aplicativo transmite (broadcasts) uma solicitação de status. Isso confirma que o app Tap on Phone está no estado Initialized. Se o status for None, você deve solicitar ao lojista que inicialize o POS.
  2. Atestação Proativa (Opcional, mas Recomendado): Para evitar atrasos inesperados na UI enquanto o cliente está esperando, seu aplicativo transmite (broadcasts) uma solicitação de atestação. Isso garante que o token de segurança do dispositivo seja válido antes de iniciar a interface de pagamento.
  3. Iniciação de Intent: Seu aplicativo inicia a POSActivity do Tap on Phone usando um Android Intent. Você passa os detalhes da transação (como o valor em centavos, o tipo de transação PURCHASE e suas credenciais de SSO).
  4. Execução do Pagamento: O app Tap on Phone assume o controle da tela. Ele solicita que o cliente aproxime seu cartão ou dispositivo, lê os dados com segurança, solicita um PIN se necessário, e se comunica com o backend para autorizar o pagamento.
  5. Callback de Resultado: Assim que o pagamento é concluído, o app Tap on Phone é fechado e retorna um ActivityResult para o seu aplicativo.

Determinando o Status Final

Quando o seu aplicativo recebe o Activity Result, você deve avaliar campos específicos para determinar se o pagamento foi bem-sucedido.

  • RESULT_CANCELED: O usuário cancelou manualmente a transação (ex: pressionando o botão de voltar), ou ocorreu um erro fatal antes que a transação pudesse ficar online. Nenhum recibo é gerado.
  • RESULT_OK: O processo de transação foi concluído e um recibo foi gerado.

RESULT_OK não significa que o pagamento foi aprovado.** Significa simplesmente que o processo terminou sem um erro fatal do sistema.

Para determinar se os fundos foram realmente garantidos, você deve inspecionar o extra status retornado dentro do intent de RESULT_OK:

  • Se status for APPROVED, o pagamento foi bem-sucedido.
  • Se status for DECLINED, o pagamento foi rejeitado pelo emissor ou rede. Você deve verificar os campos declineCause e declineError para entender o motivo.

Gerenciando Respostas Ausentes

Em ambientes móveis, os aplicativos podem falhar (crash), ou o sistema operacional Android pode encerrar seu app enquanto ele estiver em segundo plano esperando o app Tap on Phone terminar.

Se o seu aplicativo nunca receber a resposta do intent de transação, você não deve presumir que a transação falhou. O app Tap on Phone pode ter processado o pagamento com sucesso enquanto o seu app estava desconectado.

O Fluxo de Recuperação

Para recuperar um resultado de transação ausente, use o broadcast de status assíncrono:

  1. Capture o ID da Transação: Quando você inicia inicialmente o intent de pagamento, o app Tap on Phone transmite um sdkTransactionId assim que a transação começa. Seu aplicativo deve escutar o TRANSACTION_BROADCAST_RESPONSE e salvar temporariamente este UUID.
  2. Aguarde: Se o seu app perder o resultado final, aguarde pelo menos 5 a 10 segundos para garantir que o backend processou completamente a transação.
  3. Consulte o Status: Transmita um TRANSACTION_STATUS_BROADCAST contendo o UUID salvo.
  4. Processe o Resultado: O app Tap on Phone responde com os detalhes completos do recibo (permitindo que você verifique se foi APPROVED ou DECLINED) ou um erro.

Se o broadcast de recuperação retornar um erro, recomendamos tentar novamente uma vez para descartar problemas temporários de rede. Se falhar uma segunda vez, você pode considerar com segurança a transação como negada ou anulada.