● Refund · /v1 Refund
A refund is its own resource, with its own reference and status. A provider may reject a refund days later, so a failed refund has to be findable on its own.
POST /v1/payments/{uid}/refund
Multiple partial refunds are allowed. Server-side a single conditional UPDATE enforces captured_amount - refunded_amount >= amount, so concurrent duplicates cannot over-refund; exceeding it returns 409 rather than silently truncating.
Path parameters
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Body
amount | integer | Omit to refund the full amount |
reason | string | |
Response 201
uid | string | Refund reference: RF + yyyymmdd + 6-digit sequence |
payment_uid | string | |
reference_id | string | Your own refund reference, for reconciliation |
amount | integer | |
currency | string | |
currency_exponent | integer | |
status | pending | succeeded | failed | failed means the provider rejected the refund after the fact, possibly days later. You must subscribe to refund.status_changed — the synchronous response at request time is not enough |
reason | string | |
connector_code | string | |
provider_refund_id | string | The provider's refund reference, matched against the settlement file during reconciliation |
failure_code | string | Set on failure; values are the same unified decline codes |
created_at | string<date-time> | |
finished_at | string<date-time> | |
Errors
| 409 | The idempotency key was reused with a different body, or the object's state does not allow this operation |
Request
curl -X POST https://api.baton.example/v1/payments/{uid}/refund \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{
"amount": 2000,
"reason": "customer_request"
}' Response · 201
{
"uid": "RF20261116000031",
"payment_uid": "PY20261116000217A7F3",
"amount": 2000,
"currency": "USD",
"currency_exponent": 2,
"status": "pending",
"reason": "customer_request",
"connector_code": "adyen",
"created_at": "2026-11-16T09:40:12Z"
}