● 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.

Refund

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

uidrequired string

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

409The 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"
}

List refunds

GET /v1/refunds

Filter by payment or date range. For reconciliation, match provider_refund_id here against the settlement file — never match refunds by payment reference.

Query parameters

payment_uid string
status pending | succeeded | failed
reference_id string
created_from string<date-time>
created_to string<date-time>
cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└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>
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/refunds \
  -H "Authorization: Bearer sk_live_xxx"

Retrieve a refund

GET /v1/refunds/{uid}

When a payment has been refunded several times, this is the only way to tell which one failed — refunded_amount on the payment is just a running total.

Path parameters

uidrequired string

Response 200

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

404The object does not exist, or belongs to another environment or merchant
Request
curl -X GET https://api.baton.example/v1/refunds/{uid} \
  -H "Authorization: Bearer sk_live_xxx"