Refunds
Refunds allow you to return funds to a customer for a charge that was previously created. You can issue a full or partial refund for any successful payment. This process is initiated against a specific PaymentIntent.
For more details on the payment lifecycle, please refer to the Payment Intents documentation.
Refund Process Flow#
The following diagram illustrates the typical sequence of events when a refund is processed:
Initiate a Refund#
To create a refund, you need to call the refund method on a PaymentIntent object, specifying the ID of the payment you wish to refund.
Method
payment.paymentIntents.refund(id, data)Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The ID of the |
|
| The amount to refund. For a partial refund, specify an amount less than the original charge. If omitted, a full refund is processed. |
|
| The reason for the refund. Accepted values include: |
|
| An optional description of the refund for your internal records. |
Example
import payment from '@blocklet/payment-js';
async function issueRefund(paymentIntentId) {
try {
const refund = await payment.paymentIntents.refund(paymentIntentId, {
amount: '0.50',
reason: 'requested_by_customer',
description: 'Partial refund for item not received'
});
console.log('Refund initiated:', refund);
} catch (error) {
console.error('An error occurred:', error.message);
}
}
// Replace 'pi_xxx' with a valid PaymentIntent ID
issueRefund('pi_xxx');Example Response
{
"id": "rf_xxxx",
"livemode": false,
"description": "Partial refund for item not received",
"amount": "0.50",
"currency_id": "pc_xxx",
"customer_id": "cus_xxx",
"payment_intent_id": "pi_xxx",
"status": "succeeded",
"reason": "requested_by_customer",
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Refund#
You can fetch the details of a specific refund at any time using its unique id.
Method
payment.refunds.retrieve(id)Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The unique identifier of the refund to retrieve (prefixed with |
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);
} catch (error) {
console.error(`Error retrieving refund ${refundId}:`, error.message);
}
}
// Replace 'rf_xxx' with a valid Refund ID
getRefundDetails('rf_xxx');List All Refunds#
To view a history of refunds, use the list method. The results are paginated and can be filtered by various criteria.
Method
payment.refunds.list(params)Parameters
Name | Type | Description |
|---|---|---|
|
| Optional. Filter refunds for a specific customer. |
|
| Optional. Filter refunds by their status (e.g., |
|
| Optional. Filter refunds associated with a specific invoice. |
|
| Optional. Filter refunds associated with a specific subscription. |
|
| Optional. Filter refunds by a specific currency. |
|
| Optional. The page number for pagination. Defaults to |
|
| Optional. The number of items per page. Defaults to |
|
| Optional. Sort order, e.g., |
Example
import payment from '@blocklet/payment-js';
async function listCustomerRefunds(customerId) {
try {
const refunds = await payment.refunds.list({
customer_id: customerId,
pageSize: 10
});
console.log(`Found ${refunds.count} refunds for customer ${customerId}:`);
refunds.list.forEach(refund => {
console.log(`- ID: ${refund.id}, Amount: ${refund.amount}, Status: ${refund.status}`);
});
} catch (error) {
console.error('Error listing refunds:', error.message);
}
}
// Replace 'cus_xxx' with a valid Customer ID
listCustomerRefunds('cus_xxx');Example Response
{
"count": 1,
"list": [
{
"id": "rf_xxxx",
"livemode": false,
"description": "Partial refund for item not received",
"amount": "0.50",
"currency_id": "pc_xxx",
"customer_id": "cus_xxx",
"payment_intent_id": "pi_xxx",
"status": "succeeded",
"reason": "requested_by_customer",
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}
]
}The Refund Object#
A Refund object contains detailed information about the transaction. A key field to monitor is status.
pending: The refund has been initiated but is not yet confirmed.requires_action: The refund requires additional action from the customer or payment provider.succeeded: The refund was successfully processed and funds have been returned.failed: The refund could not be processed. See thefailure_reasonfield for more details.canceled: The refund was canceled before it could be processed.
You now have the tools to manage refunds effectively. To receive real-time notifications about refund status changes, you should configure endpoints to listen for these events. To learn more, proceed to the Webhooks guide.