O pagamento falhou de vez
Mesma assinatura (X-IDSAAS-Signature), mesmos headers e mesma escada de retentativas dos eventos de verificação; deduplique pelo id do evento. Chega no webhook do flow do pagamento. Falha definitiva do pedido: failure.code diz destination_rejected, pix_unavailable, canceled ou bank_rejected. Para cobrar de novo, crie um pagamento com outro reference_id.
Cabeçalhos
Assinatura HMAC (pode trazer mais de um v1 durante rotação de segredo).
Tipo do evento.
"pix_payment.failed"Corpo
Envelope dos eventos pix_payment.*. Mesma assinatura, headers e escada de retentativas dos eventos de verificação. O data é o objeto pix_payment com payer_url null, e o status é o do fato que o evento anuncia (um pix_payment.expired nunca diz succeeded; o fato seguinte tem o seu evento).
Id estável do evento (deduplique por ele): evt_<pix_payment_id>_, um por pagamento e evento.
pix_payment.succeeded, pix_payment.failed, pix_payment.expired, pix_payment.refunded Um pagamento por biometria. Nada de quem paga sai neste objeto. Campo novo pode surgir sem subir a versão: ignore chave desconhecida.
Resposta
Confirmação de recebimento. Qualquer 2xx conta; processar depois, responder já.