Skip to main content
POST
Estornar Cobrança

Visão Geral

Estorna uma cobrança já paga. O estorno pode ser total (omitindo amount) ou parcial.
Só cobranças com status paid podem ser estornadas. Para cancelar uma cobrança que ainda não foi paga (pending), use DELETE /api/v1/charges/{uuid}.

Headers

string
required
Sua chave de API (Bearer sk_live_...)
string
required
application/json

Path Parameters

string
required
UUID da cobrança

Request Body

number
Valor a estornar em BRL decimal (ex: 50.00, não 5000). Omita para estornar o total cobrado.
string
Motivo do estorno, até 500 caracteres. Fica registrado na cobrança.
O teto do estorno é o chargedTotal da cobrança, não o amount. Numa venda parcelada no cartão o cliente pagou o valor com acréscimo, e é esse valor que pode voltar: um produto de R349,00vendidoem2×porR 349,00 vendido em 2× por R 358,52 aceita estorno de até R$ 358,52.

Exemplo de Requisição

Resposta de Sucesso (200 OK)

A cobrança atualizada, agora com o bloco refund preenchido:

Estorno de Pix Automático

Cobranças de Pix Automático são estornadas via devolução — uma transferência Pix de volta, regida por regras do Banco Central. Isso muda o comportamento em um ponto importante:
A devolução não é instantânea. A resposta confirma que o estorno foi solicitado, não concluído.A cobrança fica com status: "refundPending" e o bloco refund já traz o valor, mas com refundedAt: null. Quando a transferência liquida, o status vira reversed, o refundedAt é preenchido e o webhook transaction.refunded é disparado.Use refundedAt como o sinal de que o dinheiro voltou de fato — não a resposta desta chamada.
Estornos de cartão e boleto (Celcoin) são confirmados na própria resposta. Estorno de PIX processado pela Celcoin não é suportado (veja abaixo).

Estorno de PIX (Celcoin) não é suportado

A Celcoin não oferece devolução de PIX: a API dela expõe estorno apenas para cartão e boleto, e o painel não mostra ação de estorno para um PIX pago. Um estorno de PIX processado pela Celcoin não é possível por aqui — a API recusa na hora, sem sequer tentar o provedor.
A API sinaliza esse caso com HTTP 422 e o campo code: "pix_refund_unsupported". É uma recusa definitiva — não adianta tentar de novo. Para devolver um PIX Celcoin, faça a transferência de volta manualmente ao cliente (por exemplo, um Pix de volta).
422 Unprocessable Entity
Estorno de PIX Automático (Woovi) é outro caminho e continua funcionando — veja a seção acima.

Auditoria

Todo estorno registra quem o fez. Um estorno feito pelo painel guarda o usuário responsável; um estorno feito por esta API guarda qual chave de API foi usada. Isso vale para a trilha de auditoria exigida pelo PCI DSS — mais um motivo para usar chaves distintas por integração e revogar as que não estiverem em uso.

Erros