Skip to main content
POST
Criar Estorno
Este endpoint estorna pagamentos, com suporte a estorno total e parcial. Quando a venda tem split, a reversão das fatias acontece automaticamente no motor financeiro, respeitando o que cada participante ainda deve devolver.

Parâmetros

string
required
UUID do pagamento a estornar.
integer
Valor a estornar, em centavos. Omitido = estorno total do remanescente (o servidor usa o valor exato, sem risco de arredondamento). Informado = estorno parcial.O valor não pode exceder o remanescente reembolsável (valor original menos estornos já solicitados/concluídos). Acima disso a API rejeita com 422 — nunca ajusta por conta própria.
string
Motivo do estorno (texto livre, para seu controle).
object
Obrigatório quando o pagamento é boleto (bank_slip): a conta que recebe a devolução.

Pré-requisitos

  • O pagamento precisa estar authorized ou refunded_partially. Qualquer outro status é rejeitado com 422.
  • O pagamento precisa pertencer à sua conta (a chave usada). Pagamento de outro lojista responde 404.

Exemplos de Requisição

Resposta (201 Created)

string
UUID do estorno criado.
string
UUID do pagamento estornado.
integer
Valor estornado em centavos.
string
Status do estorno. Nasce requested e evolui de forma assíncrona.Valores: requested, scheduled, success, failed, canceled
string
Derivado pelo servidor a partir do valor: full quando o valor cobre todo o remanescente, partial caso contrário.

Acompanhamento

O estorno é processado de forma assíncrona junto ao emissor. Acompanhe pelo webhook (payment.refunded quando concluído; o pagamento vai a refunded ou refunded_partially) ou por polling em GET /payments/{id}.
Estornos parciais em sequência: o remanescente reembolsável considera o valor original da venda menos tudo que já foi solicitado. Você pode estornar parcialmente várias vezes até zerar; o estorno “total” após parciais devolve exatamente o que resta.

Códigos de Erro

O payment_id não existe ou pertence a outro lojista (o escopo por conta responde 404, nunca vaza a existência do recurso).