API Reference/Refunds
POST
Create a payment refund
Create a payment refund. See the request, response and integration notes.
POST
/v1/payments/{public_id}/refundshttps://integrate.api.kyvopay.com.br
Resposta200 OK
{
"amount_centavos": 100,
"reason": "Pagamento duplicado"
}Authentication
X-API-Keystring · headerrequiredUse the ky_... key created under Integrations → API Keys in the KyvoPay dashboard.
Use this endpoint to create a payment refund. For safe retries, reuse the same idempotency key for the same business operation.
Request
Send an authenticated POST request to /v1/payments/{public_id}/refunds.
Note
Private endpoints require the X-API-Key header. Keep credentials on your backend and log the response request_id for diagnostics.
Response
Implementation notes
- Validate required input before sending the request.
- Store returned public identifiers without assuming their format.
- Treat 4xx validation errors as non-retryable until the request is corrected.
- Retry timeouts, 429 and temporary 5xx responses with exponential backoff.
- Keep the idempotency key stable across retries.