Reembolsos
Reembolse um Pix pela API da WysePay: devolução total ou parcial ao pagador, de onde sai o dinheiro, status, webhooks e prazo de 90 dias.
Um reembolso devolve ao pagador, por Pix, todo o valor de uma venda paga ou só uma parte. Você pode reembolsar pela API, no painel (no detalhe da venda) ou pedir ao suporte.
Reembolsar
POST /api/v1/transactions/{id}/refunds (permissão refunds:write):
curl -X POST https://api.wysepay.com.br/api/v1/transactions/txn_01k6g8m2v4x7z9b3c5d7f9h0j2/refunds \
-H "x-api-key: wyp_test_sua_chave" \
-H "Content-Type: application/json" \
-H "idempotency-key: devolucao-pedido-1042" \
-d '{ "amountCents": 3000, "reason": "Item fora de estoque" }'| Campo | Obrigatório | O que é |
|---|---|---|
amountCents | Não | Quanto devolver, em centavos. Sem ele, devolve tudo o que ainda não foi reembolsado. |
reason | Não | O motivo, até 140 caracteres. Vai junto com o Pix devolvido. |
A resposta é o reembolso:
{
"id": "ref_01k6g8m2v4x7z9b3c5d7f9h0j2",
"transactionId": "txn_01k6g8m2v4x7z9b3c5d7f9h0j2",
"amountCents": 3000,
"status": "PROCESSING",
"reason": "Item fora de estoque",
"failureReason": null,
"livemode": true,
"createdAt": "2026-10-05T15:30:00.000Z",
"completedAt": null
}Esta permissão tira dinheiro da conta
refunds:write vem desligada em toda chave. Ligue em Chaves de API só na chave do sistema que faz devoluções, de preferência com os IPs liberados.
De onde sai o dinheiro
- O valor sai do seu saldo na hora do pedido: primeiro do que a venda ainda tem a liberar, depois do saldo disponível.
- A taxa da venda não é devolvida. Numa venda de R$ 100,00 com R$ 1,00 de taxa, o reembolso total devolve R$ 100,00 ao pagador e tira R$ 100,00 do seu saldo.
- Sem saldo suficiente, a resposta é
409e nada acontece.
Situações (status)
| Status | Quer dizer |
|---|---|
PROCESSING | Enviado ao banco, aguardando a confirmação. Leva poucos segundos. |
SUCCEEDED | O dinheiro chegou ao pagador. Chega o webhook transaction.refunded. |
FAILED | O banco recusou. O valor volta ao seu saldo e chega o webhook refund.failed. Você pode tentar de novo. |
Acompanhe pelo webhook transaction.refunded: ele traz o reembolso e a transação atualizada. A transação continua PAID num reembolso parcial, com refundedAmountCents somando o que já voltou, e vira REFUNDED quando todo o valor foi devolvido.
Quando não dá para reembolsar
A resposta é 409, com o motivo em message, quando:
- a venda não está paga;
- todo o valor já foi devolvido;
- a venda tem um MED aberto (o valor já está bloqueado);
- passaram mais de 90 dias do pagamento (o limite do Pix);
- falta saldo para cobrir o reembolso.
Um valor maior do que o que falta devolver responde 400.
Repetir com segurança
Envie sempre a idempotency-key. Repetindo o pedido com a mesma chave, o mesmo reembolso volta e nada é devolvido duas vezes.
Listar
GET /api/v1/transactions/{id}/refunds (permissão refunds:read) lista os reembolsos da venda, do mais novo para o mais antigo.
Modo teste
Com uma chave wyp_test_, o reembolso é concluído na hora (SUCCEEDED) e o webhook transaction.refunded é enviado, sem nenhum dinheiro real. Pague a cobrança de teste antes com simular pagamento.