DOCS

Refunds

API de reembolsos parciais e totais.

POST /v1/charges/:id/refund

Cria um reembolso para uma cobrança.

Request body

CampoTipoObrigatórioDescrição
amountMoneyValor do reembolso. Se omitido, reembolso total.
reasonstringMotivo do reembolso
buyer_pix_keystringboletoChave Pix do comprador, no CPF/CNPJ dele. Obrigatória para boleto; recusada nos outros meios.

Boleto: estorno por Pix ao comprador

Nenhuma adquirente devolve um boleto pago (na Pagar.me, desde 01/10/2026, cancelar o boleto pago não devolve nada). Por isso o reembolso de um boleto sai do seu saldo, por Pix, para uma chave do próprio comprador:

  • buyer_pix_key é obrigatória. Sem ela, 422 validation_error.
  • A chave precisa estar no CPF/CNPJ do comprador (o documento do cliente da cobrança). Chave CPF/CNPJ é comparada direto; e-mail, celular (+55…) ou chave aleatória são conferidos na base do Pix (DICT). Chave de outra pessoa: 422. Nunca pagamos terceiros.
  • O valor (total ou parcial) é reservado do seu saldo na hora, e a taxa da venda não é devolvida — a mesma regra dos outros reembolsos. Se o saldo não cobrir, o Pix sai assim mesmo e seus saques ficam bloqueados até cobrir a diferença, como em qualquer reembolso.
  • A resposta vem com status: "pending", method: "pix_to_buyer" e a chave mascarada em buyer_pix_key_masked. Quando o Pix é confirmado, o reembolso vira succeeded, a cobrança vira refunded / partially_refunded e você recebe o webhook charge.refunded. Se o Pix falhar, o reembolso vira failed e o valor volta para o seu saldo.
  • Um reembolso por Pix por vez em cada cobrança: outro enquanto o primeiro está pendente recebe 409.
  • Com chave de teste (sk_test_) nenhum Pix sai: o reembolso já nasce succeeded, e só é aceita chave CPF/CNPJ igual ao documento do comprador.
curl -X POST https://api.kirvex.com.br/v1/charges/ch_01J.../refund   -u sk_live_...:   -H "Content-Type: application/json"   -H "Idempotency-Key: refund-boleto-1234"   -d '{ "buyer_pix_key": "123.456.789-09", "reason": "cliente desistiu" }'
{
  "id": "re_01J...",
  "object": "refund",
  "charge_id": "ch_01J...",
  "status": "pending",
  "method": "pix_to_buyer",
  "buyer_pix_key_masked": "***.456.789-**",
  "amount": { "amount": "10000", "currency": "BRL" },
  "charge_status": "succeeded",
  "payout_vendor": "woovi"
}

Pix recebido pela Woovi: reembolso assíncrono

O reembolso de um Pix pago pela Woovi (vendor: "woovi") é devolvido ao pagador pela própria Woovi, e a confirmação vem do banco do comprador depois da resposta:

  • A resposta (201) normalmente vem com status: "pending", charge_status ainda igual ao de antes (succeeded / partially_refunded) e raw_status com o estado na Woovi (IN_PROCESSING; UNANSWERED quando a Woovi não respondeu a tempo — o reembolso continua pendente e é conferido com a Woovi automaticamente). Raramente a Woovi já confirma na hora: aí vem status: "succeeded", raw_status: "CONFIRMED".
  • O valor é reservado do seu saldo na hora (a taxa da venda não é devolvida, como nos outros reembolsos).
  • Quando a Woovi confirma, o reembolso vira succeeded, a cobrança vira refunded / partially_refunded e só então você recebe o webhook charge.refunded (não no momento do pedido).
  • Se a Woovi ou o banco do comprador recusar, o reembolso vira failed (failure_reason traz o motivo) e o valor volta inteiro para o seu saldo; a cobrança continua paga. Não há webhook para reembolso recusado — o mesmo comportamento das outras adquirentes: consulte GET /v1/refunds/:id. Se a Woovi recusar já no pedido, a resposta é um erro (4xx/502) dizendo que nada foi reembolsado.
  • Um reembolso pendente por vez em cada cobrança: outro enquanto o primeiro está pendente recebe 409.
{
  "id": "re_01J...",
  "object": "refund",
  "charge_id": "ch_01J...",
  "status": "pending",
  "amount": { "amount": "5000", "currency": "BRL" },
  "charge_status": "succeeded",
  "vendor": "woovi",
  "raw_status": "IN_PROCESSING"
}

GET /v1/refunds e GET /v1/refunds/:id trazem method, buyer_pix_key_masked e failure_reason (null nos reembolsos feitos na adquirente).

Headers obrigatórios

HeaderDescrição
Idempotency-KeyChave única para evitar reembolsos duplicados

Exemplo

curl -X POST https://api.kirvex.com.br/v1/charges/ch_01J.../refund \
  -u sk_test_...: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-pedido-1234" \
  -d '{ "amount": { "amount": "5000", "currency": "BRL" }, "reason": "cliente desistiu" }'

Resposta (201)

{
  "id": "re_01J...",
  "object": "refund",
  "charge_id": "ch_01J...",
  "status": "pending",
  "amount": { "amount": "5000", "currency": "BRL" },
  "vendor": "pagarme",
  "vendor_ref": "or_...",
  "reason": "cliente desistiu",
  "created_at": "2026-04-29T12:01:00Z",
  "succeeded_at": null
}

GET /v1/refunds/:id

Retorna um reembolso pelo ID.


GET /v1/refunds

Lista reembolsos com paginação por cursor.

Query params

CampoTipoDescrição
cursorstringCursor da página anterior
limitnumberMáximo de resultados (1–100, default 20)
charge_idstringFiltrar por cobrança

On this page