curl --request POST \
--url https://api.example.com/v1/payment/{id}/refunds \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": "10.00",
"metadata": {
"orderReference": "order_example"
},
"reason": "requested_by_customer"
}
'{
"data": {
"amount": "10.00",
"createdAt": "2026-10-11T12:00:00.000Z",
"currency": "EUR",
"errorCode": null,
"id": "rf_example",
"metadata": {
"orderReference": "order_example"
},
"providerRefundId": null,
"reason": "requested_by_customer",
"status": "PENDING",
"transactionId": "tr_example",
"updatedAt": "2026-10-11T12:00:00.000Z"
}
}Request a full or partial refund
Accepts an asynchronous refund in the authenticated merchant and API-key mode. Omit amount to refund the remaining refundable amount. PENDING/PROCESSING are not completion. The original connection must support refunds and payment and processing currencies must match. Idempotency-Key is mandatory.
curl --request POST \
--url https://api.example.com/v1/payment/{id}/refunds \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": "10.00",
"metadata": {
"orderReference": "order_example"
},
"reason": "requested_by_customer"
}
'{
"data": {
"amount": "10.00",
"createdAt": "2026-10-11T12:00:00.000Z",
"currency": "EUR",
"errorCode": null,
"id": "rf_example",
"metadata": {
"orderReference": "order_example"
},
"providerRefundId": null,
"reason": "requested_by_customer",
"status": "PENDING",
"transactionId": "tr_example",
"updatedAt": "2026-10-11T12:00:00.000Z"
}
}Authorizations
Headers
A single 1–255 character printable ASCII value without spaces. The checkout-submit: prefix is reserved (case-insensitive). Reuse the same key and body after an uncertain response.
1 - 255^[\x21-\x7e]+$"refund-order-example-1"
Path Parameters
Payment transaction ID
32^[A-Za-z0-9_-]{1,32}$Body
Positive decimal string in the payment currency, within its currency precision. Omit to refund the remaining refundable amount.
80^(0|[1-9]\d{0,19})(\.\d{1,18})?$"10.00"
JSON object, at most 16384 UTF-8 bytes when serialized; maximum container depth 10 (root depth 0). Do not include sensitive customer or payment data.
requested_by_customer, duplicate, fraudulent, other Response
Refund accepted for asynchronous execution
Show child attributes
Show child attributes