Skip to content
Developer portal

Retrieve a refund

GET
/v1/refunds/{id}
curl --request GET \
  --url https://api.example.com/v1/refunds/example \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The object’s id.

Responses

Section titled “Responses”

200

Section titled “200”

The refund.

Media typeapplication/json
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
{
  "id": "re_01j9x3a1b2c3d4e5f6g7h8j9k0",
  "object": "refund",
  "currency": "php",
  "status": "created",
  "reason": "requested_by_customer",
  "failure_reason": "declined",
  "metadata": {
    "order_id": "1042"
  }
}

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

404

Section titled “404”

not_found: resource_missing for an id this key cannot see, route_missing for a path that does not exist.

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