KyvoPay

Reembolso

Devolve total ou parcialmente um pagamento já confirmado.

POST/v1/payments/{id}/refundsChave de API

Solicitar reembolso#

POST/v1/payments/{id}/refundsPainel

Omitir amount_centavos devolve o valor total ainda não reembolsado. Informar um valor menor faz um reembolso parcial — a cobrança passa a partially_refunded.

amount_centavosintegeropcional

Valor a devolver. Sem este campo, devolve o saldo restante da cobrança.

reasonstringopcional

Motivo registrado na auditoria. Até 255 caracteres.

Reembolso sai pelo painel

Por segurança, o reembolso é uma operação de painel e exige um usuário autenticado — não é possível dispará-lo apenas com a chave de API. Você pode consultar reembolsos via API normalmente.
POST/v1/payments/{id}/refunds
curl https://api.kyvopay.com.br/v1/payments/pay_3Kq8Zx91/refunds \
  -H "X-API-Key: $KYVO_API_KEY" \
  -H "Idempotency-Key: refund-8291" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_centavos": 5000,
    "reason": "Item devolvido pelo cliente"
  }'
200 OKresposta
{
  "data": {
    "id": "ref_7Xa2Mn45",
    "amount_centavos": 5000,
    "status": "requested",
    "reason": "Item devolvido pelo cliente",
    "created_at": "2026-08-11T20:14:02Z",
    "completed_at": null
  },
  "error": null,
  "request_id": "req_c02f7719"
}

Listar reembolsos#

GET/v1/refundsChave de API

Paginado, com os mesmos campos items, page, per_page e total. O filtro status aceita lista.

StatusSignifica
requestedSolicitado, aguardando processamento.
processingEm execução no processador.
completedValor devolvido ao pagador.
failedNão foi possível devolver. Consulte o motivo no painel.

Cada mudança dispara um webhook: payment.refunded ou payment.partially_refunded.

GET/v1/refunds
curl -G https://api.kyvopay.com.br/v1/refunds \
  -H "X-API-Key: $KYVO_API_KEY" \
  -d status=completed