Idempotência em endpoints de pagamento

O problema

Redes falham. O cliente faz um POST de pagamento, a resposta se perde, ele tenta de novo — e agora você cobrou duas vezes.

A solução

Uma idempotency key por requisição (header Idempotency-Key). No servidor:

1. Persistir a key antes de processar.
2. Se já existe, retornar a resposta anterior.
3. Se não, processar e gravar o resultado atomicamente.

INSERT INTO idempotency (key, status) VALUES ($1, 'processing')
ON CONFLICT (key) DO NOTHING;

Em sistemas financeiros, idempotência não é otimização — é requisito.