API Reference

Refunds

The Refunds API allows you to create and manage refunds for charges. A refund can be for the full amount of the original charge or a partial amount. Refunds are processed against a specific payment_intent_id.
For more details on the payment process itself, please see the Payment Intents API Reference.
The Refund Object#A Refund object contains detailed information about a specific refund transaction.
Attribute
Type
Description
id
string
Unique identifier for the refund object.
livemode
boolean
true if the object was created in live mode, false if in test mode.
description
string
An arbitrary string attached to the object.
amount
string
The amount of the refund.
currency_id
string
Three-letter ISO currency code.
customer_id
string
ID of the customer associated with this refund.
payment_intent_id
string
ID of the Payment Intent that was refunded.
invoice_id
string
(Optional) ID of the invoice associated with this refund.
subscription_id
string
(Optional) ID of the subscription associated with this refund.
metadata
object
A set of key-value pairs that you can attach to an object.
status
string
The status of the refund. Can be pending, requires_action, failed, canceled, or succeeded.
reason
string
(Optional) The reason for the refund. Can be duplicate, requested_by_customer, requested_by_admin, fraudulent, or expired_uncaptured_charge.
failure_reason
string
(Optional) If the refund fails, this provides a machine-readable failure reason.
created_at
Date
Timestamp of when the object was created.
updated_at
Date
Timestamp of the last update to the object.
Create a Refund#Creates a new refund object.
Parameters
Name
Type
Description
payment_intent_id
string
Required. The identifier of the Payment Intent to refund.
amount
string
The amount to refund. Cannot be greater than the original charge amount. If omitted, a full refund is issued.
description
string
An optional description for the refund.
reason
string
The reason for the refund. Valid options include duplicate, requested_by_customer, etc.
metadata
object
A set of key-value pairs to store with the refund object.
Returns
Returns the newly created Refund object.
Example
import payment from '@blocklet/payment-js';

async function createRefund(paymentIntentId) {
  try {
    const refund = await payment.refunds.create({
      payment_intent_id: paymentIntentId,
      amount: '500', // Refund 5.00 units of currency
      reason: 'requested_by_customer',
      metadata: { order_id: '6735' }
    });
    console.log('Refund created:', refund.id);
    return refund;
  } catch (error) {
    console.error('Error creating refund:', error.message);
  }
}

// Replace 'pi_xxxxxxxx' with a valid Payment Intent ID
createRefund('pi_xxxxxxxx');Example Response
{
  "id": "re_1J3j4k5L6m7N8o9PqRsTuVwX",
  "livemode": false,
  "description": null,
  "amount": "500",
  "currency_id": "usd",
  "customer_id": "cus_aBcDeFgHiJkLmNoP",
  "payment_intent_id": "pi_xxxxxxxx",
  "invoice_id": "in_1J3j4k5L6m7N8o9PqRsTuVwY",
  "subscription_id": null,
  "metadata": {
    "order_id": "6735"
  },
  "status": "succeeded",
  "reason": "requested_by_customer",
  "failure_reason": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:05.000Z"
}Retrieve a Refund#Retrieves the details of an existing refund.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the refund to retrieve.
Returns
Returns the Refund object if a valid ID was provided.
Example
import payment from '@blocklet/payment-js';

async function getRefundDetails(refundId) {
  try {
    const refund = await payment.refunds.retrieve(refundId);
    console.log('Retrieved refund:', refund);
    return refund;
  } catch (error) {
    console.error(`Error retrieving refund ${refundId}:`, error.message);
  }
}

// Replace 're_xxxxxxxx' with a valid Refund ID
getRefundDetails('re_xxxxxxxx');Example Response
{
  "id": "re_1J3j4k5L6m7N8o9PqRsTuVwX",
  "livemode": false,
  "description": null,
  "amount": "500",
  "currency_id": "usd",
  "customer_id": "cus_aBcDeFgHiJkLmNoP",
  "payment_intent_id": "pi_xxxxxxxx",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:05.000Z"
}List Refunds#Returns a paginated list of refunds. You can filter the list based on various parameters.
Parameters
Name
Type
Description
status
string
(Optional) Filter refunds by status (e.g., succeeded, failed).
invoice_id
string
(Optional) Only return refunds for the given invoice.
subscription_id
string
(Optional) Only return refunds for the given subscription.
currency_id
string
(Optional) Only return refunds for the given currency.
customer_id
string
(Optional) Only return refunds for the given customer.
page
number
(Optional) The page number for pagination, starting at 1.
pageSize
number
(Optional) The number of items per page. Defaults to 20.
order
string[] or string
(Optional) Sort order for the results. Example: ['created_at', 'DESC'].
Returns
Returns a paginated object containing a count of total items and a list of Refund objects.
Example
import payment from '@blocklet/payment-js';

async function listSuccessfulRefunds() {
  try {
    const refunds = await payment.refunds.list({
      status: 'succeeded',
      pageSize: 5
    });
    console.log(`Found ${refunds.count} successful refunds.`);
    refunds.list.forEach(refund => {
      console.log(`- ID: ${refund.id}, Amount: ${refund.amount}`);
    });
    return refunds;
  } catch (error) {
    console.error('Error listing refunds:', error.message);
  }
}

listSuccessfulRefunds();Example Response
{
  "count": 25,
  "list": [
    {
      "id": "re_1J3j4k5L6m7N8o9PqRsTuVwX",
      "amount": "500",
      "currency_id": "usd",
      "status": "succeeded",
      "created_at": "2023-10-27T10:00:00.000Z"
    },
    {
      "id": "re_2K4k5l6M7n8O9p0QrStUvWxY",
      "amount": "1200",
      "currency_id": "usd",
      "status": "succeeded",
      "created_at": "2023-10-26T14:30:00.000Z"
    }
  ]
}Search Refunds#Returns a paginated list of refunds that match a search query.
Parameters
Name
Type
Description
query
string
Required. The search term to find refunds. This can be a customer email, a description, or an ID.
page
number
(Optional) The page number for pagination, starting at 1.
pageSize
number
(Optional) The number of items per page. Defaults to 20.
Returns
Returns a paginated object containing a count of total items and a list of matching Refund objects.
Example
import payment from '@blocklet/payment-js';

async function searchForRefund(query) {
  try {
    const results = await payment.refunds.search({ query: query });
    console.log(`Found ${results.count} refunds matching '${query}'.`);
    results.list.forEach(refund => {
      console.log(`- ID: ${refund.id}, Status: ${refund.status}`);
    });
    return results;
  } catch (error) {
    console.error('Error searching refunds:', error.message);
  }
}

searchForRefund('pi_xxxxxxxx');Example Response
{
  "count": 1,
  "list": [
    {
      "id": "re_1J3j4k5L6m7N8o9PqRsTuVwX",
      "amount": "500",
      "currency_id": "usd",
      "payment_intent_id": "pi_xxxxxxxx",
      "status": "succeeded",
      "reason": "requested_by_customer",
      "created_at": "2023-10-27T10:00:00.000Z"
    }
  ]
}
After managing refunds, you might want to explore how to handle Webhooks to receive real-time notifications for events like refund.succeeded.

Attribute	Type	Description
`id`	`string`	Unique identifier for the refund object.
`livemode`	`boolean`	`true` if the object was created in live mode, `false` if in test mode.
`description`	`string`	An arbitrary string attached to the object.
`amount`	`string`	The amount of the refund.
`currency_id`	`string`	Three-letter ISO currency code.
`customer_id`	`string`	ID of the customer associated with this refund.
`payment_intent_id`	`string`	ID of the Payment Intent that was refunded.
`invoice_id`	`string`	(Optional) ID of the invoice associated with this refund.
`subscription_id`	`string`	(Optional) ID of the subscription associated with this refund.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`status`	`string`	The status of the refund. Can be `pending`, `requires_action`, `failed`, `canceled`, or `succeeded`.
`reason`	`string`	(Optional) The reason for the refund. Can be `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, or `expired_uncaptured_charge`.
`failure_reason`	`string`	(Optional) If the refund fails, this provides a machine-readable failure reason.
`created_at`	`Date`	Timestamp of when the object was created.
`updated_at`	`Date`	Timestamp of the last update to the object.

Name	Type	Description
`payment_intent_id`	`string`	Required. The identifier of the Payment Intent to refund.
`amount`	`string`	The amount to refund. Cannot be greater than the original charge amount. If omitted, a full refund is issued.
`description`	`string`	An optional description for the refund.
`reason`	`string`	The reason for the refund. Valid options include `duplicate`, `requested_by_customer`, etc.
`metadata`	`object`	A set of key-value pairs to store with the refund object.

Name	Type	Description
`status`	`string`	(Optional) Filter refunds by status (e.g., `succeeded`, `failed`).
`invoice_id`	`string`	(Optional) Only return refunds for the given invoice.
`subscription_id`	`string`	(Optional) Only return refunds for the given subscription.
`currency_id`	`string`	(Optional) Only return refunds for the given currency.
`customer_id`	`string`	(Optional) Only return refunds for the given customer.
`page`	`number`	(Optional) The page number for pagination, starting at 1.
`pageSize`	`number`	(Optional) The number of items per page. Defaults to 20.
`order`	`string[]` or `string`	(Optional) Sort order for the results. Example: `['created_at', 'DESC']`.

Name	Type	Description
`query`	`string`	Required. The search term to find refunds. This can be a customer email, a description, or an ID.
`page`	`number`	(Optional) The page number for pagination, starting at 1.
`pageSize`	`number`	(Optional) The number of items per page. Defaults to 20.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Refunds

The Refund Object#

Create a Refund#

Retrieve a Refund#

List Refunds#

Search Refunds#

Webhooks

Settings