退款

退款 API 允许您创建和管理收费的退款。退款可以是原始收费的全部金额，也可以是部分金额。退款是针对特定的 payment_intent_id 处理的。

有关支付流程本身的更多详情，请参阅 Payment Intents API 参考。

Refund 对象#

Refund 对象包含有关特定退款交易的详细信息。

属性	类型	描述
id	string	退款对象的唯一标识符。
livemode	boolean	如果对象是在生产模式下创建的，则为 true；如果在测试模式下创建的，则为 false。
description	string	附加到对象的任意字符串。
amount	string	退款金额。
currency_id	string	三位字母的 ISO 货币代码。
customer_id	string	与此退款关联的客户 ID。
payment_intent_id	string	被退款的 Payment Intent 的 ID。
invoice_id	string	（可选）与此退款关联的发票 ID。
subscription_id	string	（可选）与此退款关联的订阅 ID。
metadata	object	可以附加到对象的一组键值对。
status	string	退款状态。可以是 pending、requires_action、failed、canceled 或 succeeded。
reason	string	（可选）退款原因。可以是 duplicate、requested_by_customer、requested_by_admin、fraudulent 或 expired_uncaptured_charge。
failure_reason	string	（可选）如果退款失败，此字段提供一个机器可读的失败原因。
created_at	Date	对象创建时的时间戳。
updated_at	Date	对象最后更新的时间戳。

创建退款#

创建一个新的退款对象。

参数

名称	类型	描述
payment_intent_id	string	必需。 要退款的 Payment Intent 的标识符。
amount	string	要退款的金额。不能大于原始收费金额。如果省略，将进行全额退款。
description	string	退款的可选描述。
reason	string	退款原因。有效选项包括 duplicate、requested_by_customer 等。
metadata	object	与退款对象一起存储的一组键值对。

返回

返回新创建的 Refund 对象。

示例

响应示例

检索退款#

检索现有退款的详细信息。

参数

名称	类型	描述
id	string	必需。 要检索的退款的唯一标识符。

返回

如果提供了有效的 ID，则返回 Refund 对象。

示例

响应示例

列出退款#

返回一个分页的退款列表。您可以根据各种参数筛选列表。

参数

名称	类型	描述
status	string	（可选）按状态（例如 succeeded、failed）筛选退款。
invoice_id	string	（可选）仅返回指定发票的退款。
subscription_id	string	（可选）仅返回指定订阅的退款。
currency_id	string	（可选）仅返回指定货币的退款。
customer_id	string	（可选）仅返回指定客户的退款。
page	number	（可选）用于分页的页码，从 1 开始。
pageSize	number	（可选）每页的项目数。默认为 20。
order	string[] or string	（可选）结果的排序顺序。示例：['created_at', 'DESC']。

返回

返回一个分页对象，其中包含项目总数 count 和 Refund 对象列表 list。

示例

响应示例

搜索退款#

返回与搜索查询匹配的分页退款列表。

参数

名称	类型	描述
query	string	必需。 用于查找退款的搜索词。可以是客户电子邮件、描述或 ID。
page	number	（可选）用于分页的页码，从 1 开始。
pageSize	number	（可选）每页的项目数。默认为 20。

返回

返回一个分页对象，其中包含项目总数 count 和匹配的 Refund 对象列表 list。

示例

响应示例

管理退款后，您可能想了解如何处理 Webhooks 以接收 refund.succeeded 等事件的实时通知。