Fallback no fluxo transacional

Webhook: updated-sub-transaction

Objetivo

Este fallback atua como um mecanismo de segurança, assegurando consistência do status transacional.

Premissas

• A transação é criada inicialmente com status PENDING.
• O webhook updated-sub-transaction é responsável por notificar mudanças de status.
• O webhook pode falhar por motivos externos (timeout, bloqueio de infraestrutura, indisponibilidade temporária).
• A API da Paytime é considerada fonte de verdade para o status final da transação.

Estratégia Recomendada

1. Persistência Inicial

   1. No momento da criação da transação, armazene localmente:
   2. _id (ID da Transação;
   3. status inicial (PENDING)
   4. created_at

2. Fluxo Normal (Via Webhook)

   1. Quando o webhook updated-sub-transaction for recebido:
   2. Localizar a transação pelo _id.
   3. Verificar o status recebido.
   4. Atualizar o status local, quando aplicável.
   5. Registrar data e origem da atualização (webhook).
      

3. Condição de Ativação do Fallback

   1. O fallback deve ser executado quando:
   2. A transação permanece com status PENDING após um tempo pré-definido
      (ex.:1,2,3,6,10 ou 15 minutos) após a criação, e
   3. Nenhum webhook de atualização foi processado com sucesso.
      

4. Execução do Fallback

   1. Passo 1 – Consulta ativa da transação
   2. JSON

      GET /v1/marketplace/transactions/{_id}

      
      

5. Validação do Status

   1. A partir da resposta da API:
   2. Se o status retornado diferente do salvo localmente:
      1. Atualizar o status local da transação para PAID
      2. Registrar que a atualização ocorreu via fallback
   3. Se o status permanecer PENDING:
      1. Manter o status local
      2. Reagendar nova verificação, respeitando política de retry
         

6. Atualização do Status Local (Exemplo Lógico)

   Exemplo de atualização de Status de Pending para PAID

Status local: PENDING
Status retornado pela API: PAID

→ Atualizar status local para PAID
→ Registrar origem da atualização: FALLBACK
→ Registrar data/hora da atualização

Fluxo Resumido

Exemplo de atualização de Status de Pending para PAID

Criação da transação (PENDING)
        ↓
Webhook updated-sub-transaction
        ↓
Status atualizado para PAID
        ↓
[Fallback]
Se webhook não recebido em X minutos
        ↓
GET /transactions/{id}
        ↓
Status = PAID
        ↓
Atualização local do status

Boas Práticas

• Utilize backoff exponencial para novas tentativas de fallback.
• Evite consultas excessivas à API.
• Centralize logs de:
  • Webhooks recebidos
  • Fallbacks executados
• Nunca altere o status sem validação direta na API da Paytime.
• Este fallback garante que o status da transação reflita corretamente a realidade do pagamento, reduzindo impactos operacionais e financeiros causados por falhas de comunicação assíncrona.