API reference
Create a refund
Refund an approved payment in full or in part.
POST
/v1/payments/{payment_id}/refundsThe payment must be approved or partially_refunded. The refund uses the payment currency. Pending refunds count against the refundable balance, so two refunds cannot exceed the payment together.
Path parameters
payment_idstring required- The payment id, starting with pay_.
Headers
Idempotency-Keystring required- A unique key for this operation, up to 255 characters. Retrying with the same key and body returns the original response. See Idempotency.
Body parameters
amountinteger- Minor units, greater than 0. Leave it out to refund the whole remaining balance.
Request
Response
{
"id": "ref_01JBX8A1B2C3D4E5F6G7H8J9KM",
"payment_id": "pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA",
"provider_refund_id": "987654321",
"amount": 500000,
"currency": "ARS",
"status": "approved",
"provider_status": "approved",
"failure_code": null,
"created_at": "2026-11-12T16:10:00Z",
"updated_at": "2026-11-12T16:10:02Z"
}Errors
| Status | When |
|---|---|
202 | The provider did not give a definitive answer (a timeout, for example). The resource is returned with status unknown and Camel reconciles it. Do not create it again. |
401 | The API key is missing, malformed, or revoked. |
404 | No payment with this id in this environment. |
409 | The payment is not refundable in its state, the amount exceeds the remaining balance, or the connection is unavailable. |
409 | The Idempotency-Key was used with a different body, or the first request is still running. |
422 | The body is invalid. |
429 | Too many requests. Wait for Retry-After seconds. |
502 | The provider returned an error. The body is still the resource, with status failed. |