A trava contra cobrança repetida existe desde a v0.21.1 e funciona: se a mesma pessoa, no mesmo produto, pelo mesmo meio e no mesmo valor aparece duas vezes em 60 segundos, a segunda não vira uma cobrança nova.

Só que ela estava ignorando um sinal seu.

O que estava acontecendo

Quem integra pela API pode mandar o cabeçalho X-Idempotency-Key em cada cobrança. Ele serve justamente para dizer o que é a mesma operação e o que não é: repetir a chave significa "é a mesma compra, não cobre de novo"; mandar uma chave nova significa "esta é outra compra".

A trava não estava olhando para isso. Se você mandasse uma chave nova e diferente — dizendo com todas as letras que era outra venda — e por acaso fosse o mesmo cliente, no mesmo produto, no mesmo valor, dentro de 60 segundos, a API respondia 200 com a cobrança anterior.

Não é um erro que aparece. Você recebia sucesso, só que a segunda venda nunca existiu. Quem vende duas vagas no mesmo curso para a mesma pessoa, ou dois meses do mesmo plano em sequência, fechava o dia com uma cobrança a menos do que a conciliação dizia — e sem nada no log apontando para isso.

O que mudou

Quando você manda uma chave de idempotência, ela passa a fazer parte da identidade da cobrança. Na prática:

• Chaves diferentes = vendas diferentes. As duas passam, as duas são cobradas, as duas aparecem.
• A mesma chave continua sendo uma cobrança só. Isso não afrouxou: se o seu código repetir a chamada depois de um timeout com a mesma chave, continua existindo uma cobrança só. Essa parte é o que impede a cobrança em dobro, e ela segue no lugar.
• Quem não manda chave não muda nada. A página de pagamento e quem integra sem o cabeçalho continuam exatamente como estavam.

O que fazer

Se você já manda X-Idempotency-Key derivado de algo estável do seu lado — o id do pedido, o id da reserva — não precisa fazer nada: passou a funcionar como você já esperava.

Se você ainda não manda, vale passar a mandar. É o que torna uma repetição de chamada segura, e agora também é como você diz que duas vendas parecidas são mesmo duas vendas.

X-Idempotency-Key: pedido:4472:cobranca

Um aviso que vale repetir: a chave só protege se a mesma chave voltar na repetição. Chave sorteada a cada chamada não protege de nada — foi exatamente isso que causou a cobrança tripla de setembro. Nossos SDKs não fazem mais isso.