Changelog da API

Mudanças de contrato da API do cliente final (https://api.monetarie.com), em ordem cronológica inversa. Toda mudança que altera código HTTP, campo obrigatório ou formato de resposta aparece aqui antes de valer em produção ou, quando isso não foi possível, com a data em que passou a valer.

2026-08-31 · Devolução PIX: motivo validado, Idempotency-Key obrigatória, resposta sempre 202

Em produção desde 31/08/2026 18:59 BRT. Afeta POST /api/external/pix/refund (Devolução PIX).

O que mudou

Antes	Agora
reason (alias return_code) aceitava qualquer texto; um código fora da pacs.004 era saneado no fio para BE08 (a devolução saía como "falha operacional" mesmo quando você pediu fraude)	reason aceita somente BE08, FR01, MD06 e SL02 (os quatro códigos do leiaute pacs.004 do SPI). Qualquer outro valor responde 422 síncrono com a mensagem código de devolução inválido; válidos: BE08, FR01, MD06, SL02 e nada é enviado. Sem reason, o default continua MD06
Idempotency-Key opcional	Idempotency-Key obrigatória (8 a 180 caracteres, charset A-Za-z0-9._:-). Sem ela: 400 idempotency_key_required. Reenviar a mesma chave faz replay do mesmo comando, nunca uma segunda devolução
Em alguns caminhos a resposta era 200 com o end_to_end_id da devolução já preenchido	A resposta é sempre 202 com end_to_end_id: null. O e2e da devolução (D...) e o desfecho chegam por webhook: pix.refund.requested e depois pix.refund.completed ou pix.refund.failed

Códigos de motivo

Código	Quando usar
MD06	Devolução solicitada pelo recebedor (o usuário da sua conta). É o default
BE08	Falha operacional do recebedor
FR01	Fraude (relato do recebedor)
SL02	Devolução por decisão do PSP do recebedor (MED, Mecanismo Especial de Devolução)

O que fazer

1. Gere uma Idempotency-Key por comando de devolução (por exemplo, o id do pedido de devolução no seu sistema) e reenvie a mesma chave em qualquer retry.
2. Trate o 422 de motivo inválido e o 400 idempotency_key_required como erro de integração (não é falha do PIX): corrija o payload e reenvie.
3. Não espere o end_to_end_id na resposta: assine pix.refund.requested, pix.refund.completed e pix.refund.failed.

Por que

Um código de motivo inválido chegava ao BACEN como BE08, o que classificava como "falha operacional" devoluções pedidas por fraude ou por MED. A validação síncrona devolve o erro para quem pode corrigir. A Idempotency-Key obrigatória fecha a porta da devolução duplicada em retry de rede.

2026-08-30 · external_id opcional e idempotente por conta, em cash-in e cash-out

external_id continua opcional. Quando informado, é único por conta e idempotente: reenviar o mesmo external_id na mesma conta devolve a mesma ordem (cash-out) ou a mesma cobrança (cash-in), nunca uma segunda. O espaço de nomes é compartilhado entre cash-in e cash-out na mesma conta. Consulta por external_id em Consultar por External ID.