退款
退款允许你将先前已创建的收费款项退还给客户。你可以为任何成功的付款发起全额或部分退款。此过程针对特定的 PaymentIntent 发起。
有关支付生命周期的更多详情，请参阅 Payment Intents 文档。
退款处理流程#
下图说明了处理退款时事件的典型顺序：
发起退款#
要创建退款，你需要在 PaymentIntent 对象上调用 refund 方法，并指定你希望退款的支付 ID。
方法
payment.paymentIntents.refund(id, data)参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要退款的 |
|
| 要退款的金额。如需部分退款，请指定一个小于原始收费的金额。如果省略，将处理全额退款。 |
|
| 退款原因。接受的值包括： |
|
| 供你内部记录的可选退款描述。 |
示例
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: '部分退款，因未收到商品'
});
console.log('退款已发起：', refund);
} catch (error) {
console.error('发生错误：', error.message);
}
}
// 将 'pi_xxx' 替换为有效的 PaymentIntent ID
issueRefund('pi_xxx');响应示例
{
"id": "rf_xxxx",
"livemode": false,
"description": "部分退款，因未收到商品",
"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"
}检索退款#
你可以随时使用其唯一的 id 获取特定退款的详细信息。
方法
payment.refunds.retrieve(id)参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要检索的退款的唯一标识符（前缀为 |
示例
import payment from '@blocklet/payment-js';
async function getRefundDetails(refundId) {
try {
const refund = await payment.refunds.retrieve(refundId);
console.log('退款状态：', refund.status);
} catch (error) {
console.error(`检索退款 ${refundId} 时出错：`, error.message);
}
}
// 将 'rf_xxx' 替换为有效的退款 ID
getRefundDetails('rf_xxx');列出所有退款#
要查看退款历史记录，请使用 list 方法。结果是分页的，并且可以按各种标准进行筛选。
方法
payment.refunds.list(params)参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 可选。筛选特定客户的退款。 |
|
| 可选。按退款状态（例如 |
|
| 可选。筛选与特定发票关联的退款。 |
|
| 可选。筛选与特定订阅关联的退款。 |
|
| 可选。按特定货币筛选退款。 |
|
| 可选。分页的页码。默认为 |
|
| 可选。每页的项目数。默认为 |
|
| 可选。排序顺序，例如 |
示例
import payment from '@blocklet/payment-js';
async function listCustomerRefunds(customerId) {
try {
const refunds = await payment.refunds.list({
customer_id: customerId,
pageSize: 10
});
console.log(`为客户 ${customerId} 找到 ${refunds.count} 条退款记录：`);
refunds.list.forEach(refund => {
console.log(`- ID: ${refund.id}, 金额: ${refund.amount}, 状态: ${refund.status}`);
});
} catch (error) {
console.error('列出退款时出错：', error.message);
}
}
// 将 'cus_xxx' 替换为有效的客户 ID
listCustomerRefunds('cus_xxx');响应示例
{
"count": 1,
"list": [
{
"id": "rf_xxxx",
"livemode": false,
"description": "部分退款，因未收到商品",
"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"
}
]
}退款对象#
Refund 对象包含有关交易的详细信息。需要监控的一个关键字段是 status。
pending: 退款已发起，但尚未确认。requires_action: 退款需要客户或支付提供商采取额外行动。succeeded: 退款已成功处理，资金已退还。failed: 无法处理退款。有关更多详细信息，请参阅failure_reason字段。canceled: 退款在处理前已被取消。
现在你已拥有有效管理退款的工具。要接收有关退款状态变化的实时通知，你应该配置端点来监听这些事件。要了解更多信息，请继续阅读 Webhooks 指南。