Refunds | ArcBlock

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.

Create a Refund

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.

Response Example

{
  "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.

Retrieve a Refund

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.

Response Example

{
  "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.

List Refunds

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.

Response Example

{
  "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.

Search Refunds

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.

Response Example

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