Job de verificação de transações
Toda transação Pix começa como pendente. Na maioria dos casos, ela é rapidamente confirmada ou rejeitada pelo PSTI, mas às vezes essa confirmação atrasa ou se perde. O job de verificação de transações periodicamente escaneia transações travadas em pendente e consulta o PSTI para uma atualização.
Fluxo: Verificação de status
Como funciona:- Após um breve atraso (30 segundos), o job verifica se há transações ainda marcadas como pendentes.
- Se a transação foi confirmada, ela é marcada como confirmada.
- Se falhou, o sistema reverte o débito e atualiza o status para falha.
- Se ainda está pendente, o job agenda outra verificação.
Fila de retentativa de webhooks
Se o seu sistema falha ao processar um webhook, por exemplo, devido a um timeout ou erro do servidor, o plugin Pix não desiste. Entregas de webhook que falharam são adicionadas a uma fila de retentativa com backoff exponencial:
| Tentativa | Atraso antes da retentativa |
|---|---|
| 1a | Imediato |
| 2a | 10 segundos |
| 3a | 1 minuto |
| 4a | 5 minutos |
| … | Até 24 horas |
Recuperação de estorno
Em casos raros, tentativas de estorno podem ter sucesso parcial, por exemplo:
- O valor é creditado de volta ao remetente.
- Mas a etapa de confirmação é perdida
- Ou a entrega do webhook falha
O que torna isso confiável?
- Stateful por design: Toda transação Pix inclui uma trilha de auditoria completa e status do ciclo de vida.
- Lógica de compensação nativa: Se algo quebra, o sistema sabe como completar ou desfazer com segurança.
- Respeito à idempotência: Retentativas e jobs repetidos não produzem resultados duplicados.
Parâmetros configuráveis
Você pode ajustar o comportamento dos jobs usando as seguintes variáveis de ambiente:
| Variável | Descrição | Padrão |
|---|---|---|
PENDING_JOB_INTERVAL | Com que frequência verificar transações pendentes. | 30 segundos |
MAX_TRANSACTION_RETRIES | Máximo de tentativas antes de marcar como falha. | 5 |
RETRY_BACKOFF_BASE | Atraso base para retentativas de webhook | 10 segundos |
MAX_RETRY_TTL | Duração máxima para retentativas de webhook | 24 horas |
O que você precisa fazer
Você não precisa configurar nada; os jobs são totalmente gerenciados pelo plugin Pix. Para garantir que tudo funcione bem:
- Use IDs únicos e rastreáveis para suas transações e contas.
- Monitore a entrega de webhooks e os status das transações.
- Nos avise se precisar de suporte para replay de webhooks ou visibilidade na execução dos jobs.