Skip to main content
POST
Create a refund

Authorizations

Authorization
string
header
required

A secret key, sk_test_... or sk_live_...; a publishable key (pk_...) on the browser routes only

Body

application/json
payment
string
required

A payment of yours that succeeded.

Required string length: 1 - 64
Example:

"pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf"

amount
integer

In the smallest unit of the currency. Omit it to refund everything that has not been refunded yet; above that remaining balance the request is refused.

Example:

2500

reason
string

Shown on the refund in RevOS and on the receipt.

Required string length: 1 - 200
Example:

"Customer returned the item"

Response

The refund

object
enum<string>
required
Available options:
refund
id
string
required
Example:

"re_test_3kQ2mL7Hs1pXv4cR8tWzAbCdEf"

payment
string
required

The payment the money goes back on.

Example:

"pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf"

status
enum<string>
required

pending while the processor has the refund but has not confirmed it (a later webhook says how it ended); succeeded once the money is on its way back; failed when the processor refused (the create then answers 402 and this object stays readable).

Available options:
pending,
succeeded,
failed
Example:

"succeeded"

amount
integer
required

In the smallest unit of the currency (cents).

Example:

2500

currency
enum<string>
required
Available options:
USD,
CAD
Example:

"USD"

reason
string | null
required
Example:

"Customer returned the item"

failure
object | null
required

Set when status is failed: why, in the same fixed vocabulary as a payment failure. processing_error is a fault on the way to the processor, safe to retry with a new Idempotency-Key.

livemode
boolean
required
Example:

false

created_at
string<date-time>
required
Example:

"2026-09-22T20:00:00.000Z"

succeeded_at
string<date-time> | null
required
Example:

"2026-09-22T20:00:01.312Z"