API Reference

Refunds

Refund objects represent the return of funds to a customer for a previous charge. This can be a full or partial refund. This section details how to create, retrieve, and manage refunds using the SDK.
The Refund Object#A TRefundExpanded object contains detailed information about a specific refund transaction.
Attribute
Type
Description
id
string
Unique identifier for the refund object.
amount
string
The total amount of the refund, in the smallest currency unit (e.g., cents).
currency_id
string
The ID of the currency used for the refund.
customer_id
string
The ID of the customer associated with this refund.
payment_intent_id
string
The ID of the Payment Intent that was refunded.
status
string
The status of the refund. Can be pending, succeeded, failed, or canceled.
reason
string
The reason for the refund. Possible values are duplicate, requested_by_customer, requested_by_admin, fraudulent, or expired_uncaptured_charge.
description
string
A description of the refund provided by you.
livemode
boolean
true if the refund was created in live mode, false for test mode.
metadata
object
A set of key-value pairs that you can attach to a refund object.
created_at
string
The timestamp when the refund was created.
customer
object
The expanded Customer object.
paymentCurrency
object
The expanded Payment Currency object.
paymentMethod
object
The expanded Payment Method object.
paymentIntent
object
The expanded Payment Intent object.
invoice
object
The expanded Invoice object, if applicable.
subscription
object
The expanded Subscription object, if applicable.
Create a Refund#Initiates a refund for a previously completed charge.
Endpoint: POST /api/refunds
Parameters
Name
Type
Description
amount
string
A positive integer string representing how much of this charge to refund. Cannot be greater than the available-to-refund amount of the charge.
currency_id
string
The ID of the currency for the amount.
customer_id
string
The ID of the customer to associate with the refund.
payment_method_id
string
The ID of the payment method used for the original charge.
payment_intent_id
string
The identifier of the Payment Intent to refund.
reason
string
Reason for the refund. Must be one of duplicate, requested_by_customer, requested_by_admin, fraudulent, expired_uncaptured_charge.
description
string
An explanation of the refund, with a maximum of 200 characters.
metadata
object
A set of key-value pairs to store with the refund. See details below.
invoice_id
string
Optional. The ID of the invoice associated with the charge.
subscription_id
string
Optional. The ID of the subscription associated with the charge.
Metadata Object Properties
The metadata object allows you to store custom information as key-value pairs. Both keys and values must be strings.
Key
Value
Description
string
string
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
Returns
Returns the newly created TRefundExpanded object.
Example
import payment from '@blocklet/payment-js';

async function createRefund() {
  try {
    const refund = await payment.refunds.create({
      payment_intent_id: 'pi_xxxxxxxxxxxxxx',
      amount: '5000', // e.g., $50.00 if currency decimal is 2
      currency_id: 'usd_xxxxxxxxxxxxxx',
      customer_id: 'cus_xxxxxxxxxxxxxx',
      payment_method_id: 'pm_xxxxxxxxxxxxxx',
      reason: 'requested_by_customer',
      description: 'Customer requested a partial refund for unsatisfactory service.',
      metadata: {
        support_ticket_id: 'tkt_12345'
      }
    });
    console.log('Refund created:', refund.id);
    return refund;
  } catch (error) {
    console.error('Error creating refund:', error.message);
  }
}

createRefund();Example Response
{
  "id": "rf_123456789",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxxxx",
  "status": "pending",
  "reason": "requested_by_customer",
  "description": "Customer requested a partial refund for unsatisfactory service.",
  "livemode": false,
  "metadata": {
    "support_ticket_id": "tkt_12345"
  },
  "created_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Refund#Fetches the details of an existing refund by its unique ID.
Endpoint: GET /api/refunds/{id}
Parameters
Name
Type
Description
id
string
The unique identifier of the refund to retrieve.
Returns
Returns the TRefundExpanded object for the specified refund.
Example
import payment from '@blocklet/payment-js';

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

getRefundDetails('rf_123456789');Example Response
{
  "id": "rf_123456789",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "customer": { 
    "id": "cus_xxxxxxxxxxxxxx",
    "name": "John Doe"
  },
  "paymentCurrency": { 
    "id": "usd_xxxxxxxxxxxxxx", 
    "name": "US Dollar"
  },
  "paymentIntent": { 
    "id": "pi_xxxxxxxxxxxxxx"
  },
  "created_at": "2023-10-27T10:00:00.000Z"
}List all Refunds#Retrieves a paginated list of all refunds. You can filter the results using various parameters.
Endpoint: GET /api/refunds
Parameters
Name
Type
Description
page
number
Optional. The page number for pagination, starting from 1. Defaults to 1.
pageSize
number
Optional. The number of objects to return per page. Defaults to 20.
status
string
Optional. Filter refunds by status. Provide a comma-separated string for multiple statuses (e.g., 'succeeded,failed').
invoice_id
string
Optional. Filter refunds by a specific invoice ID.
subscription_id
string
Optional. Filter refunds associated with a specific subscription ID.
currency_id
string
Optional. Filter refunds by a specific currency ID.
customer_id
string
Optional. Filter refunds for a specific customer.
payment_intent_id
string
Optional. Filter refunds related to a specific Payment Intent.
livemode
boolean
Optional. Filter refunds by their live mode status.
metadata.{key}
string
Optional. Filter by custom metadata fields. Use the format metadata.yourKey=yourValue.
Returns
Returns a paginated list object containing count, list of TRefundExpanded objects, and paging information.
Example
import payment from '@blocklet/payment-js';

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

listSucceededRefunds();Example Response
{
  "count": 15,
  "list": [
    {
      "id": "rf_abcdefgh",
      "amount": "1000",
      "status": "succeeded",
      "customer_id": "cus_xxxxxxxxxxxxxx",
      "created_at": "2023-10-26T14:30:00.000Z"
    },
    {
      "id": "rf_ijklmnop",
      "amount": "2500",
      "status": "succeeded",
      "customer_id": "cus_yyyyyyyyyyyyyy",
      "created_at": "2023-10-25T09:00:00.000Z"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}Search Refunds#Performs a search for refunds based on a key-value query string.
Endpoint: GET /api/refunds/search
Parameters
Name
Type
Description
q
string
A key-value based query string. For example, customer_id:cus_123,status:succeeded.
page
number
Optional. The page number for pagination. Defaults to 1.
pageSize
number
Optional. The number of results per page. Defaults to 20.
o
string
Optional. The sort order, either asc or desc for created_at. Defaults to desc.
livemode
boolean
Optional. Filter refunds by their live mode status.
Returns
Returns a paginated list object containing count, list of TRefundExpanded objects, and paging information that match the search criteria.
Example
import payment from '@blocklet/payment-js';

async function searchForRefunds() {
  try {
    const response = await payment.refunds.search({
      q: 'customer_id:cus_xxxxxxxxxxxxxx,status:succeeded',
      pageSize: 10
    });
    console.log(`Found ${response.count} refunds for the customer.`);
    response.list.forEach(refund => {
      console.log(`- Refund ID: ${refund.id}`);
    });
    return response;
  } catch (error) {
    console.error('Error searching refunds:', error.message);
  }
}

searchForRefunds();Example Response
{
  "count": 3,
  "list": [
    {
      "id": "rf_abcdefgh",
      "amount": "1000",
      "status": "succeeded",
      "customer_id": "cus_xxxxxxxxxxxxxx",
      "created_at": "2023-10-26T14:30:00.000Z"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}This guide covers the available methods for managing refunds. For details on the original charges, see the Payment Intents documentation.

Attribute	Type	Description
`id`	`string`	Unique identifier for the refund object.
`amount`	`string`	The total amount of the refund, in the smallest currency unit (e.g., cents).
`currency_id`	`string`	The ID of the currency used for the refund.
`customer_id`	`string`	The ID of the customer associated with this refund.
`payment_intent_id`	`string`	The ID of the Payment Intent that was refunded.
`status`	`string`	The status of the refund. Can be `pending`, `succeeded`, `failed`, or `canceled`.
`reason`	`string`	The reason for the refund. Possible values are `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, or `expired_uncaptured_charge`.
`description`	`string`	A description of the refund provided by you.
`livemode`	`boolean`	`true` if the refund was created in live mode, `false` for test mode.
`metadata`	`object`	A set of key-value pairs that you can attach to a refund object.
`created_at`	`string`	The timestamp when the refund was created.
`customer`	`object`	The expanded Customer object.
`paymentCurrency`	`object`	The expanded Payment Currency object.
`paymentMethod`	`object`	The expanded Payment Method object.
`paymentIntent`	`object`	The expanded Payment Intent object.
`invoice`	`object`	The expanded Invoice object, if applicable.
`subscription`	`object`	The expanded Subscription object, if applicable.

Name	Type	Description
`amount`	`string`	A positive integer string representing how much of this charge to refund. Cannot be greater than the available-to-refund amount of the charge.
`currency_id`	`string`	The ID of the currency for the amount.
`customer_id`	`string`	The ID of the customer to associate with the refund.
`payment_method_id`	`string`	The ID of the payment method used for the original charge.
`payment_intent_id`	`string`	The identifier of the Payment Intent to refund.
`reason`	`string`	Reason for the refund. Must be one of `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, `expired_uncaptured_charge`.
`description`	`string`	An explanation of the refund, with a maximum of 200 characters.
`metadata`	`object`	A set of key-value pairs to store with the refund. See details below.
`invoice_id`	`string`	Optional. The ID of the invoice associated with the charge.
`subscription_id`	`string`	Optional. The ID of the subscription associated with the charge.

Name	Type	Description
`page`	`number`	Optional. The page number for pagination, starting from 1. Defaults to `1`.
`pageSize`	`number`	Optional. The number of objects to return per page. Defaults to `20`.
`status`	`string`	Optional. Filter refunds by status. Provide a comma-separated string for multiple statuses (e.g., `'succeeded,failed'`).
`invoice_id`	`string`	Optional. Filter refunds by a specific invoice ID.
`subscription_id`	`string`	Optional. Filter refunds associated with a specific subscription ID.
`currency_id`	`string`	Optional. Filter refunds by a specific currency ID.
`customer_id`	`string`	Optional. Filter refunds for a specific customer.
`payment_intent_id`	`string`	Optional. Filter refunds related to a specific Payment Intent.
`livemode`	`boolean`	Optional. Filter refunds by their live mode status.
`metadata.{key}`	`string`	Optional. Filter by custom metadata fields. Use the format `metadata.yourKey=yourValue`.

Name	Type	Description
`q`	`string`	A key-value based query string. For example, `customer_id:cus_123,status:succeeded`.
`page`	`number`	Optional. The page number for pagination. Defaults to `1`.
`pageSize`	`number`	Optional. The number of results per page. Defaults to `20`.
`o`	`string`	Optional. The sort order, either `asc` or `desc` for `created_at`. Defaults to `desc`.
`livemode`	`boolean`	Optional. Filter refunds by their live mode status.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Refunds

The Refund Object#

Create a Refund#

Retrieve a Refund#

List all Refunds#

Search Refunds#

Subscription Items

Meters