Estornar uma cobrança
Devolve ao comprador o valor de uma cobrança já paga, no todo ou em parte. O corpo tem no máximo um campo: quanto devolver. Sem ele, tudo.
Autenticação
Chave de API no cabeçalho Authorization: Bearer naut_live_….
O escopo exigido é charges:refund. Uma credencial sem esse escopo recusa com 401, o mesmo código de uma credencial inválida: a recusa não diz se ela existe.
Exige chave de API no cabeçalho. A família da chave decide contra qual ambiente ela escreve, e a chave não fabrica sessão: ela não alcança nenhuma rota fora de /v1.
Parâmetros
Caminho
| Nome | Tipo | Descrição |
|---|---|---|
referenceobrigatório | texto (uuid) | A referência da cobrança a estornar. |
Cabeçalho
| Nome | Tipo | Descrição |
|---|---|---|
idempotency-key | texto | Necessária. A especificação a declara opcional, mas a rota recusa com 400 sem ela, e o motivo é o peso do estorno: uma retentativa de rede sem chave devolveria o mesmo dinheiro duas vezes. Repita SEMPRE com a mesma chave; nunca cunhe uma nova para tentar de novo. |
Corpo da requisição
application/json.
| Campo | Tipo | Descrição |
|---|---|---|
amountCents | inteiro (centavos) | Quanto devolver, em centavos inteiros. Ausente significa o valor total da cobrança. |
{
"amountCents": 129900
}Respostas
200 · sucesso
{
"amountCents": 129900,
"chargeId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"createdAt": "2026-01-15T12:00:00.000Z",
"currency": "BRL",
"method": "pix",
"payable": {
"emv": "exemplo",
"kind": "pix",
"qrImageUrl": "https://loja.exemplo.com.br/webhooks"
},
"refundedAmountCents": 129900,
"status": "pending"
}400 · requisição inválida
O header idempotency-key não veio; nenhum estorno foi registrado.
401 · não autenticado
A chave de API não foi apresentada, ou não vale.
404 · não encontrado
A referência não existe, ou não é desta conta.
409 · conflito
A cobrança não pode ser estornada com este valor agora.
429 · excesso de chamadas
Excesso de chamadas para esta chave.
503 · indisponível
Duas causas, e o code as separa. V1_REFUND_UNAVAILABLE: o seu pedido de estorno foi registrado e ainda não concluiu, então repita a MESMA requisição com a MESMA chave de idempotência daqui a instantes, e nunca cunhe uma chave nova. SANDBOX_UNAVAILABLE: a sua chave é de sandbox e o ambiente de teste desta instalação não está provisionado, e aí repetir não resolve.
Erros desta rota
| Status | Código | Quando | O que fazer |
|---|---|---|---|
| 400 | V1_IDEMPOTENCY_KEY_REQUIRED | A chamada chegou sem o cabeçalho idempotency-key. Nenhum estorno foi registrado. | Gere um valor por tentativa de estorno e reenvie. Reusar a MESMA chave nas retentativas daquela tentativa é o que impede o estorno em dobro. |
| 401 | UNAUTHORIZED | A chave de API não veio no cabeçalho, veio malformada, foi revogada, ou não pertence a esta instalação. | Confira o cabeçalho e o prefixo da chave. Repetir com a mesma chave devolve sempre 401, e nenhuma chamada desta superfície funciona sem uma chave válida. |
| 404 | V1_CHARGE_NOT_FOUND | A referência não existe nesta instalação, ou existe e pertence a outra conta. As duas causas respondem igual de propósito: distinguir revelaria a existência de cobrança alheia. | Confira a referência que a criação da cobrança devolveu. Repetir não muda o resultado. |
| 409 | V1_CHARGE_NOT_REFUNDABLE | A cobrança não admite estorno com este valor agora: ela não foi paga, já foi estornada por inteiro, ou o valor pedido passa do que ainda resta dela. | Consulte a cobrança e veja quanto dela ainda pode ser estornado. Repetir com o mesmo valor devolve sempre 409. |
| 429 | API_KEY_RATE_LIMITED | Esta chave passou do teto de chamadas da janela corrente. É limite de FREQUÊNCIA, não de valor. | Espere a janela virar e reenvie, espaçando as chamadas. Nenhum estorno foi registrado por esta chamada. |
| 503 | SANDBOX_UNAVAILABLE | A sua chave é da família de teste e esta instalação não tem o ambiente de teste provisionado. Chaves de produção seguem funcionando normalmente. | Use uma chave de produção, ou peça o provisionamento do ambiente de teste. Repetir com a chave de teste não resolve, e nenhum estorno foi registrado. |
| 503 | V1_REFUND_UNAVAILABLE | O seu pedido de estorno FOI REGISTRADO e ainda não concluiu. É o outro 503 desta operação, e o code é a única coisa que o separa de SANDBOX_UNAVAILABLE: aqui repetir é a ação correta, lá repetir não resolve. | Repita a MESMA requisição com a MESMA idempotency-key daqui a instantes. Nunca cunhe uma chave nova: ela abriria um segundo estorno da mesma cobrança. |
Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.