O pagamento foi aprovado, mas meu sistema não atualizou. O que verifico?

Na maior parte dos casos o pagamento existe e está aprovado. O que falhou foi o caminho entre a notificação e o seu banco de dados. Comece confirmando o estado pela consulta direta à transação, não pelo corpo do webhook que você guardou.

1. Localize a transação pelo identificador do pedido ou do pagamento e confirme o estado atual na área de transações da conta.
2. Consulte o mesmo pagamento pela API e compare com o estado gravado no seu banco de dados. Se divergirem, o problema está na sua ingestão, não no processamento.
3. Verifique o histórico de entregas daquele evento e qual resposta o seu endpoint devolveu. Entrega concluída é a que recebe resposta de sucesso do seu lado; erro e timeout entram na política de retentativa descrita na documentação.
4. Meça quanto tempo o seu endpoint leva para responder. Endpoint que valida a assinatura, grava o evento e responde em seguida falha menos do que endpoint que processa tudo antes de responder.
5. Revise a validação de assinatura. Corpo reserializado, encoding alterado ou proxy que reescreve o payload derrubam eventos legítimos como se fossem inválidos.
6. Reprocesse o evento pela sua fila com idempotência. A mesma chave não pode gerar dois pedidos, dois acessos ou dois e-mails.
7. Libere pedido ou acesso somente depois de confirmar o estado aprovado na consulta.

Casos comuns

• Endpoint responde sucesso e engole o erro. O evento é dado como entregue e não volta. Responda sucesso só depois de persistir o evento e processe em seguida.
• Eventos fora de ordem. Em cenário de retentativa, um estorno pode chegar antes da aprovação. Guarde o estado com carimbo de tempo e aplique apenas transições válidas, em vez de sobrescrever com o último evento recebido.
• Duplicidade de evento. Reenvio é comportamento esperado, não defeito. Use o identificador do evento, ou o do pagamento na falta dele, como chave de idempotência e devolva a mesma resposta para a mesma chave.
• Ambiente trocado. Credencial de teste apontando para webhook de produção, ou o contrário, produz exatamente esse sintoma.
• Bloqueio de rede. Firewall, WAF ou limite de requisições do seu lado podem rejeitar as entregas antes de elas chegarem à aplicação.

Enquanto você investiga

Se o cliente já pagou e está cobrando o acesso, confirme o estado da transação na consulta e libere manualmente, registrando o identificador do pagamento junto ao pedido. Liberação manual sem essa confirmação é o caminho mais curto para entregar em cima de um pagamento que não se concretizou.

Webhook é notificação, não fonte de verdade. Toda liberação de acesso deve ser confirmada por consulta ao estado do pagamento. O padrão de eventos, assinatura e retentativa está documentado em https://docs.somosmarcha.com/.