Skip to main content
POST
Sem o campo amount, o estorno devolve todo o saldo restante da cobrança. Para um estorno parcial, envie amount em centavos (mínimo de 100).
O estorno é assíncrono. A resposta 200 traz status: "refund_processing". O resultado final chega pelos webhooks charge.refunded ou charge.partial_refunded.
Só uma cobrança paga pode ser estornada, e apenas um estorno por vez. A disponibilidade do estorno depende da adquirente que processou a cobrança, não da configuração da conta: quando ela não suporta a operação, a resposta é 422 (refund_not_supported).
Depois de um estorno parcial confirmado, a cobrança fica partially_refunded, e amount_refunded e amount_refundable mostram o valor estornado e o saldo restante.
Envie o header Idempotency-Key para reenviar com segurança. Veja Idempotência e limites.

Authorizations

​
Authorization
string
header
required

Chave de API (secret key) da conta, no formato sk_live_... (produção) ou sk_test_... (Ambiente de Sandbox). Envie no header Authorization: Bearer <chave>. Autentica todas as rotas da API v2 e as rotas de Análise de Fraude. A chave identifica a conta, então a API v2 não usa o header account. Uma chave só é aceita no ambiente em que foi criada. Gere a sua no dashboard em Configurações → Chaves de API.

Headers

​
Idempotency-Key
string

Chave de idempotência opcional e recomendada. Tem até 128 caracteres e vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a resposta original (mesmo status e mesmo corpo), sem processar de novo. Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode ser reutilizada. A mesma chave com um corpo diferente retorna 422 (idempotency_key_conflict), uma requisição original ainda em andamento retorna 409 (idempotency_key_in_use) e uma chave com mais de 128 caracteres retorna 400 (idempotency_key_invalid).

Maximum string length: 128
Example:

"pedido-1024-tentativa-1"

Path Parameters

​
id
string
required

Identificador do recurso (o campo id devolvido pela API)

Body

application/json
​
amount
integer

Valor a estornar, em centavos de real. Sem amount, estorna todo o saldo restante. Um estorno parcial precisa ser de pelo menos 100 centavos.

Required range: x >= 1
Example:

3000

Response

Estorno solicitado. A cobrança fica em refund_processing até a confirmação

Visão financeira de um pagamento

​
id
string
Example:

"cha_8Kq2Lm9XvB3nT7pZ"

​
object
enum<string>
Available options:
charge
​
amount
integer

Valor cobrado, em centavos de real

Example:

10000

​
currency
enum<string>

Sempre brl

Available options:
brl
Example:

"brl"

​
original_amount
integer

Valor na moeda enviada, em centavos. Igual a amount em BRL

Example:

10000

​
original_currency
string

Moeda enviada, em minúsculas

Example:

"brl"

​
exchange_rate
number | null

Cotação usada: 1 unidade da moeda original = exchange_rate reais. null quando a moeda é BRL.

Example:

null

​
status
enum<string>

failed também cobre cobranças canceladas e expiradas. refund_processing: um estorno foi pedido e aguarda confirmação.

Available options:
pending,
paid,
refund_processing,
partially_refunded,
refunded,
chargeback,
failed
​
paid
boolean

A cobrança foi paga (inclusive se depois foi estornada)

​
captured
boolean

A cobrança foi capturada (mesmo valor de paid)

​
amount_refunded
integer

Valor já estornado, em centavos de real

Example:

0

​
amount_refundable
integer

Valor que ainda pode ser estornado, em centavos de real

Example:

10000

​
payment_method_details
object
​
payment_intent
string

O id do pagamento correspondente no pedido ou na fatura

Example:

"cha_8Kq2Lm9XvB3nT7pZ"