Changelog

Toda cobrança passa a ser gravada antes de ir ao adquirente, com o novo status processing. Ela vira pending quando o Pix é emitido, ou failed quando o adquirente recusa, com o motivo no novo campo failure_reason.

O erro ACQUIRER_REJECTED continua em 422 e agora traz charge_id. Repetir o pedido com a mesma Idempotency-Key devolve a cobrança falha, não emite outra.

O webhook_url enviado em POST /v1/charges e POST /v1/payouts agora recebe todos os eventos daquele recurso, assinados com o webhook_secret. Não é preciso cadastrar endpoint antes, e essa passa a ser a forma recomendada de integrar.

URLs locais ou de rede privada são recusadas com INVALID_WEBHOOK_URL, inclusive no cadastro de endpoints. Os eventos de pagamento passam a trazer reference, e os de cobrança trazem reference também nas mudanças de status, não só na criação.

Os eventos passaram a se chamar <recurso>.<método>.<ação>: charge.pix.paid no lugar de charge.paid, charge.boleto.emitted, payment.ted.completed. O método faz parte do nome, e só existem as combinações elegíveis.

O corpo da entrega passou a usar o vocabulário público do resto da API: envelope com resource, method e action, status igual ao de GET /v1/charges e valor em centavos inteiros. Os eventos payout.* viraram payment.* e agora são de fato entregues.

Endpoints já cadastrados foram convertidos: quem assinava charge.paid passou a assinar os três métodos, então continua recebendo o que recebia. O que muda no seu lado é o nome que chega em X-Webhook-Event e o formato do corpo.

Cobranças Pix em /v1/charges, transferências Pix em /v1/payouts, saldo em /v1/balance, dados da conta em /v1/account e gestão de webhooks em /v1/webhooks.

Autenticação por chave única no header x-api-key, com escopos por chave. Idempotência obrigatória nas criações. Paginação por cursor nas listagens.

Podemos adicionar campos novos nas respostas, valores novos em enums e endpoints novos sem aviso. Escreva o cliente ignorando campos que não conhece e tratando valor de enum desconhecido como um caso genérico, em vez de estourar.

Não vamos remover campo, renomear campo, mudar tipo nem mudar o significado de um código de erro dentro da v1.

Entrega de charge.*.expired, charge.card.authorized e payment.*.completed, limite de requisições por chave e suporte a boleto e cartão nas cobranças.