退款
退款对象代表向客户返还先前收费的资金。您可以创建新的退款、检索现有退款的详情，并列出所有退款以用于会计核算。创建退款时，其初始状态为 pending，并将被异步处理。
退款对象#
一个典型的退款对象包含以下关键属性：
- id：退款对象的唯一标识符。
- amount：退款总额，以最小货币单位（例如，美分）表示。
- currency_id：用于退款的货币标识符。
- status：退款的当前状态。可以是
pending、succeeded、failed或canceled。 - reason：退款原因。可能的值包括
duplicate、requested_by_customer、requested_by_admin、fraudulent或expired_uncaptured_charge。 - payment_intent_id：已退款的支付意图的 ID。
- customer_id：退款发放给的客户的 ID。
- description：退款的描述。
- metadata：您可以附加到对象上以供自己参考的一组键值对。
- created_at：创建退款时的时间戳。
创建退款#
创建一个 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', // 注意：amount 是一个字符串，表示以主要单位（例如，美元）计的值
currency_id: 'usd_xxxxxxxx',
customer_id: 'cus_xxxxxxxx',
payment_method_id: 'pm_xxxxxxxx',
reason: 'requested_by_customer',
description: '订单 #54321 的退款',
metadata: { order_id: '54321' }
});
console.log('退款已发起:', refund);
} catch (error) {
console.error('创建退款时出错:', error.message);
}
}
issueRefund();参数
Name | Type | Description |
|---|---|---|
|
| 必需。 一个正数字符串，表示要退还此笔收费的金额。退款金额不能超过该收费剩余的可退款金额。 |
|
| 必需。 退款的货币标识符。 |
|
| 必需。 与退款关联的客户标识符。 |
|
| 必需。 用于原始收费的支付方式标识符。 |
|
| 必需。 要退款的 PaymentIntent 的标识符。 |
|
| 必需。 表示退款原因的字符串。支持的值为 |
|
| 必需。 附加到对象的任意字符串。通常用于向用户显示。最多 200 个字符。 |
|
| 可选。您可以附加到退款对象的一组键值对。这对于以结构化格式存储附加信息很有用。 |
|
| 可选。与此退款关联的发票 ID。 |
|
| 可选。与此退款关联的订阅 ID。 |
返回
返回创建的退款对象。
响应示例
{
"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"
}检索退款#
通过其唯一 ID 检索现有退款的详情。
检索退款
import payment from '@blocklet/payment-js';
async function getRefundDetails(refundId) {
try {
const refund = await payment.refunds.retrieve(refundId);
console.log('退款详情:', refund);
} catch (error) {
console.error(`检索退款 ${refundId} 时出错:`, error.message);
}
}
getRefundDetails('ref_xxxxxxxxxxxx');参数
Name | Type | Description |
|---|---|---|
|
| 必需。 要检索的退款的唯一标识符。 |
返回
如果提供了有效的 ID，则返回 Refund 对象。否则会抛出错误。
响应示例
{
"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": { ... }
}列出所有退款#
返回所有退款的分页列表。您可以根据各种条件筛选列表。
列出退款
import payment from '@blocklet/payment-js';
async function listSuccessfulRefunds() {
try {
const response = await payment.refunds.list({
status: 'succeeded',
pageSize: 10
});
console.log(`找到 ${response.count} 条成功的退款。`);
response.list.forEach(refund => {
console.log(`- 退款 ID: ${refund.id}, 金额: ${refund.amount}`);
});
} catch (error) {
console.error('列出退款时出错:', error.message);
}
}
listSuccessfulRefunds();参数
Name | Type | Description |
|---|---|---|
|
| 可选。分页的页码，从 1 开始。默认为 |
|
| 可选。每页返回的对象数量。默认为 |
|
| 可选。一个用逗号分隔的字符串，用于按状态筛选退款（例如， |
|
| 可选。仅返回给定发票的退款。 |
|
| 可选。仅返回给定订阅的退款。 |
|
| 可选。仅返回给定货币的退款。 |
|
| 可选。仅返回给定客户的退款。 |
返回
返回一个分页对象，其中包含退款对象的 list、总数 count 和 paging 信息。
响应示例
{
"count": 15,
"list": [
{
"id": "ref_xxxxxxxxxxxx",
"object": "refund",
"amount": "5000",
"status": "succeeded",
// ...其他退款字段
}
// ...更多退款对象
],
"paging": {
"page": 1,
"pageSize": 10
}
}搜索退款#
对您的退款执行搜索查询。这对于构建自定义搜索功能非常有用。
搜索退款
import payment from '@blocklet/payment-js';
async function searchForRefund(query) {
try {
const response = await payment.refunds.search({ q: query });
console.log(`'${query}' 的搜索结果:`);
response.list.forEach(refund => {
console.log(`- 退款 ID: ${refund.id}`);
});
} catch (error) {
console.error('搜索退款时出错:', error.message);
}
}
searchForRefund('customer_id:cus_xxxxxxxx');参数
Name | Type | Description |
|---|---|---|
|
| 必需。 搜索查询字符串。支持键值筛选（例如， |
|
| 可选。分页的页码。默认为 |
|
| 可选。每页返回的对象数量。默认为 |
|
| 可选。指定结果的顺序。使用 |
返回
返回一个分页对象，其中包含匹配的退款对象的 list、总数 count 和 paging 信息。
响应示例
{
"count": 1,
"list": [
{
"id": "ref_xxxxxxxxxxxx",
"object": "refund",
"amount": "5000",
"customer_id": "cus_xxxxxxxx",
"status": "succeeded",
// ...其他退款字段
}
],
"paging": {
"page": 1,
"pageSize": 20
}
}