# Ciclo de Vida da Transação

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.

<Callout type="warning">

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

</Callout>

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.