Skip to main content
POST
Os valores aqui são inteiros em centavos: R$ 100,00 se envia como 10000. Decimais são recusados com 422, e o porquê está em Valores em centavos.
Envie Idempotency-Key nesta chamada e você pode repetir com tranquilidade depois de um erro de rede: a mesma chave devolve o recurso que já existe, em vez de criar um segundo. Veja Idempotência.
Sem amount, devolvemos o que ainda cabe estornar — e não o valor da venda. Numa cobrança já devolvida pela metade, mandar o valor cheio de volta tiraria o dinheiro duas vezes do vendedor.
amount, fee_returned e seller_debit respondem perguntas diferentes e por isso vêm separados. A aritmética está em Estornos.

Authorizations

​
Authorization
string
header
required

Chave secreta do vendedor, criada no painel em Desenvolvedores.

O valor em claro existe uma única vez, na criação. Guardamos só o hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto: um dump do nosso banco não permite cobrar em nome de ninguém.

A chave vai no servidor. Colocá-la no navegador do comprador a entrega a qualquer pessoa que abra a página.

Headers

​
Idempotency-Key
string

Identificador único da SUA tentativa. Use o mesmo valor ao repetir a requisição depois de um erro de rede.

Opcional, mas recomendado em toda criação de cobrança e estorno. Sem ele, uma repetição cria uma segunda cobrança.

Maximum string length: 255

Path Parameters

​
code
string
required

Código público da cobrança, no formato ch_….

Pattern: ^ch_[0-9a-z]{26}$

Body

application/json
​
amount
integer<int64>

Quanto devolver, em centavos inteiros. Omita para devolver todo o saldo estornável da cobrança.

Required range: x >= 1
​
reason
string | null

Motivo, para o seu histórico e o nosso.

Maximum string length: 255

Response

Estorno registrado e enviado ao provedor.

​
object
string
required
Allowed value: "refund"
​
id
string
required
Example:

"rf_01k1y7c3n8b5w2q9r4t6y8u1i3"

​
status
enum<string>
required

failed significa que a devolução não aconteceu e o saldo do vendedor foi reposto. A linha permanece de propósito: uma tentativa de devolver dinheiro que não deu certo é exatamente o que alguém vai procurar depois.

Available options:
pending,
succeeded,
failed
​
amount
integer<int64>
required

O que volta ao comprador, em centavos inteiros. Do ponto de vista dele o estorno é sempre integral: a política de taxa decide quem financia, nunca quanto ele recebe.

​
currency
string
required
Allowed value: "BRL"
​
charge
string

Código da cobrança estornada.

​
fee_returned
integer<int64>

Quanto da nossa taxa devolvemos, em centavos inteiros.

​
seller_debit
integer<int64>

O que efetivamente sai do saldo do vendedor, em centavos inteiros. Sempre amount - fee_returned. Pode ser MAIOR que o líquido recebido na venda, quando a política retém o custo que o provedor não devolve.

​
reason
string | null
​
failed_reason
string | null

Preenchido quando status é failed.

​
created_at
string<date-time>
​
processed_at
string<date-time> | null