Refunds

Refund objects represent the return of funds to a customer for a previous charge. You can create new refunds, retrieve details for an existing one, and list all refunds for accounting purposes. When a refund is created, it is initially in a pending state and will be processed asynchronously.

The Refund Object#

A typical Refund object contains the following key attributes:

• id: Unique identifier for the refund object.
• amount: The total amount refunded, in the smallest currency unit (e.g., cents).
• currency_id: The identifier of the currency used for the refund.
• status: The current status of the refund. Can be pending, succeeded, failed, or canceled.
• reason: The reason for the refund. Possible values include duplicate, requested_by_customer, requested_by_admin, fraudulent, or expired_uncaptured_charge.
• payment_intent_id: The ID of the Payment Intent that was refunded.
• customer_id: The ID of the Customer to whom the refund was issued.
• description: A description of the refund.
• metadata: A set of key-value pairs that you can attach to the object for your own reference.
• created_at: The timestamp when the refund was created.

Create a Refund#

Creates a Refund object to refund a charge that has previously been created. This can be for the full amount of the charge or a partial amount.

import payment from '@blocklet/payment-js';

async function issueRefund() {
  try {
    const refund = await payment.refunds.create({
      payment_intent_id: 'pi_xxxxxxxxxxxx',
      amount: '50.00', // Note: amount is a string representing the value in major units (e.g., dollars)
      currency_id: 'usd_xxxxxxxx',
      customer_id: 'cus_xxxxxxxx',
      payment_method_id: 'pm_xxxxxxxx',
      reason: 'requested_by_customer',
      description: 'Refund for order #54321',
      metadata: { order_id: '54321' }
    });
    console.log('Refund initiated:', refund);
  } catch (error) {
    console.error('Error creating refund:', error.message);
  }
}

issueRefund();

Parameters

Name	Type	Description
amount	string	Required. A positive string representing how much of this charge to refund. Cannot refund more than the charge's remaining refundable amount.
currency_id	string	Required. The identifier of the currency for the refund.
customer_id	string	Required. The identifier of the customer associated with the refund.
payment_method_id	string	Required. The identifier of the payment method used for the original charge.
payment_intent_id	string	Required. The identifier of the PaymentIntent to refund.
reason	string	Required. String indicating the reason for the refund. Supported values are duplicate, requested_by_customer, requested_by_admin, fraudulent, expired_uncaptured_charge.
description	string	Required. An arbitrary string attached to the object. Often useful for displaying to users. Maximum 200 characters.
metadata	object	Optional. A set of key-value pairs that you can attach to a refund object. This can be useful for storing additional information in a structured format.
invoice_id	string	Optional. The ID of the invoice that's associated with this refund.
subscription_id	string	Optional. The ID of the subscription that's associated with this refund.

Returns

Returns the created Refund object.

{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "pending",
  "description": "Refund for order #54321",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z"
}

Retrieve a Refund#

Retrieves the details of an existing refund by its unique ID.

import payment from '@blocklet/payment-js';

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

getRefundDetails('ref_xxxxxxxxxxxx');

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. Throws an error otherwise.

{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "description": "Refund for order #54321",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "customer": { ... },
  "paymentCurrency": { ... },
  "paymentIntent": { ... },
  "paymentMethod": { ... }
}

List all Refunds#

Returns a paginated list of all refunds. You can filter the list based on various criteria.

import payment from '@blocklet/payment-js';

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

listSuccessfulRefunds();

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. A comma-separated string to filter refunds by status (e.g., 'succeeded,pending').
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.

Returns

Returns a paginated object containing a list of Refund objects, the total count, and paging information.

{
  "count": 15,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "status": "succeeded",
      // ... other refund fields
    }
    // ... more refund objects
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

Search for Refunds#

Performs a search query against your refunds. This is useful for building custom search functionality.

import payment from '@blocklet/payment-js';

async function searchForRefund(query) {
  try {
    const response = await payment.refunds.search({ q: query });
    console.log(`Search results for '${query}':`);
    response.list.forEach(refund => {
      console.log(`- Refund ID: ${refund.id}`);
    });
  } catch (error) {
    console.error('Error searching refunds:', error.message);
  }
}

searchForRefund('customer_id:cus_xxxxxxxx');

Parameters

Name	Type	Description
q	string	Required. The search query string. Supports key-value filtering (e.g., status:succeeded).
page	number	Optional. The page number for pagination. Defaults to 1.
pageSize	number	Optional. The number of objects to return per page. Defaults to 20.
o	string	Optional. Specifies the order of the results. Use asc for ascending or desc for descending. Defaults to desc based on created_at.

Returns

Returns a paginated object containing a list of matching Refund objects, the total count, and paging information.

{
  "count": 1,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "customer_id": "cus_xxxxxxxx",
      "status": "succeeded",
      // ... other refund fields
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}