Refunds
API de reembolsos parciais e totais.
POST /v1/charges/:id/refund
Cria um reembolso para uma cobrança.
Request body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | Money | Valor do reembolso. Se omitido, reembolso total. | |
reason | string | Motivo do reembolso | |
buyer_pix_key | string | boleto | Chave 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 embuyer_pix_key_masked. Quando o Pix é confirmado, o reembolso virasucceeded, a cobrança virarefunded/partially_refundede você recebe o webhookcharge.refunded. Se o Pix falhar, o reembolso virafailede 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á nascesucceeded, 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 comstatus: "pending",charge_statusainda igual ao de antes (succeeded/partially_refunded) eraw_statuscom o estado na Woovi (IN_PROCESSING;UNANSWEREDquando 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í vemstatus: "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 virarefunded/partially_refundede só então você recebe o webhookcharge.refunded(não no momento do pedido). - Se a Woovi ou o banco do comprador recusar, o reembolso vira
failed(failure_reasontraz 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: consulteGET /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
| Header | Descrição |
|---|---|
Idempotency-Key | Chave ú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
| Campo | Tipo | Descrição |
|---|---|---|
cursor | string | Cursor da página anterior |
limit | number | Máximo de resultados (1–100, default 20) |
charge_id | string | Filtrar por cobrança |