Skip to content
Developer portal

List refunds

GET
/v1/refunds
curl --request GET \
  --url 'https://api.example.com/v1/refunds?limit=10' \
  --header 'Authorization: Bearer <token>'

Your refunds in this key’s mode, oldest first.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 10 >= 1 <= 100

How many objects to return, from 1 to 100.

cursor
string

A next_cursor from the previous page.

payment_intent
string

Only this intent’s refunds.

Responses

Section titled “Responses”

200

Section titled “200”

A page of refunds.

Media typeapplication/json
object
object
required
string
Allowed value: list
data
required
Array
has_more
required
boolean
next_cursor
required

Pass back as cursor for the next page. null on the last page.

string | null
data
required
Array<object>
object
id
string
object
string
Allowed value: refund
payment_intent
string
amount
integer
currency

A three-letter ISO 4217 code, in lower case.

string
/^[a-z]{3}$/
status

created for the moment it is made, processing while it is on its way, then succeeded or failed. awaiting_approval while the platform’s risk team looks at it before it is sent: it then goes on, or fails as risk_declined. Nothing is refunded while it waits, and the amount stays held against what the payment has left to refund.

string
Allowed values: created processing awaiting_approval succeeded failed
reason
string | null
Allowed values: requested_by_customer duplicate fraudulent
failure_reason

Why it failed, when it did.

string | null
Allowed values: declined refund_not_possible refund_not_yet_available refunds_not_enabled restricted risk_declined unknown
metadata

Your own key-value pairs, returned as given and carried in webhooks: up to 50 keys of up to 40 characters without square brackets, each with a text value of up to 500 characters.

object
<= 50 properties
key
additional properties
string
<= 500 characters
livemode
boolean
created

A Unix timestamp.

integer
Example
{
  "object": "list",
  "data": [
    {
      "id": "re_01j9x3a1b2c3d4e5f6g7h8j9k0",
      "object": "refund",
      "currency": "php",
      "status": "created",
      "reason": "requested_by_customer",
      "failure_reason": "declined",
      "metadata": {
        "order_id": "1042"
      }
    }
  ]
}

400

Section titled “400”

validation_failure: invalid_parameter for a parameter missing or not valid, named in param; invalid_json for a body that is not JSON; unsupported_media_type for a body that is not sent as JSON; not_acceptable when the request will not accept JSON; method_not_allowed for an HTTP method the path does not take.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure",
    "code": "invalid_parameter",
    "message": "A whole number of minor units, from 1 to 999999999999999999.",
    "param": "amount",
    "request_id": "req_4f1c0b2e9a7d"
  }
}

401

Section titled “401”

authentication_failure: access_token_required when no token was sent, invalid_access_token when it is not valid, has expired, or is a client secret. Sent with a WWW-Authenticate: Bearer header, which adds error="invalid_token" when a token was sent.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

403

Section titled “403”

authorization_failure with merchant_mismatch: a Merchant-Id header, query parameter or body field names a merchant or tenant other than the key’s.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

503

Section titled “503”

dependency_failure with service_unavailable: something on our side, or a payment network behind it, did not answer. This call only reads, so nothing was changed; retry.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}