支付意图
支付意图 (Payment Intent) 是一个表示您向客户收款意图的对象，并跟踪支付过程的生命周期。它是 PaymentKit API 中的核心对象，控制着从客户到您的资金流动。支付意图可以与 结账会话 关联，用于面向用户的支付流程，也可以直接用于服务器端操作。
本文档详细介绍了如何使用 SDK 管理支付意图对象。
支付意图对象#
支付意图对象包含有关交易的详细信息。展开后，它还可以包含相关对象。
对象属性
属性 | 类型 | 描述 |
|---|---|---|
|
| 对象的唯一标识符。 |
|
| 支付意图的状态。可能的值为 |
|
| 计划收取的金额。 |
|
| 目前已收到的金额。 |
|
| 此次支付所用货币的 ID。 |
|
| 此支付意图所属客户的 ID（如果存在）。 |
|
| 此支付意图所属发票的 ID（如果存在）。 |
|
| 此支付意图所用支付方式的 ID。 |
|
| 一组可以附加到对象的键值对。 |
|
| 对象创建时的时间戳。 |
可展开的对象
检索时，支付意图对象可以包含以下可展开的对象：
customer: 完整的Customer对象。paymentCurrency: 完整的PaymentCurrency对象。paymentMethod: 完整的PaymentMethod对象。invoice: 完整的Invoice对象（如适用）。subscription: 完整的Subscription对象（如适用）。checkoutSession: 创建此支付意图的CheckoutSession。
检索支付意图#
检索先前创建的支付意图的详细信息。当提供了 client_secret 时，允许使用可发布的密钥进行客户端检索。
检索支付意图
const paymentIntent = await payment.paymentIntents.retrieve(
'pi_123456789'
);
console.log(paymentIntent);参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 要检索的支付意图的 ID。 |
返回值
如果提供了有效的 ID，则返回一个 PaymentIntent 对象。否则，将抛出错误。
响应示例
{
"id": "pi_123456789",
"status": "succeeded",
"amount": "1000",
"amount_received": "1000",
"currency_id": "cur_xxxxxxxx",
"customer_id": "cus_xxxxxxxx",
"invoice_id": "in_xxxxxxxx",
"payment_method_id": "pm_xxxxxxxx",
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"paymentCurrency": {
/* ... 支付货币详情 ... */
},
"paymentMethod": {
/* ... 支付方式详情 ... */
},
"customer": {
/* ... 客户详情 ... */
},
"invoice": {
/* ... 发票详情 ... */
},
"subscription": null,
"checkoutSession": {See all 3 lines
更新支付意图#
通过设置传入参数的值来更新支付意图对象。任何未提供的参数都将保持不变。请注意，只能通过此方法更新 metadata。
更新支付意图
const paymentIntent = await payment.paymentIntents.update(
'pi_123456789',
{
metadata: { order_id: '6735' }
}
);
console.log(paymentIntent);参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 要更新的支付意图的 ID。 |
|
| 一组存储在对象上的键值对。 |
返回值
返回更新后的 PaymentIntent 对象。
响应示例
{
"id": "pi_123456789",
"status": "succeeded",
"amount": "1000",
"metadata": {
"order_id": "6735"
},
// ... 其他属性
}列出所有支付意图#
返回您的支付意图列表。这些意图按创建日期排序，最新的意图会最先显示。
列出支付意图
const paymentIntents = await payment.paymentIntents.list({
limit: 5,
status: 'succeeded'
});
console.log(paymentIntents);参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 可选。用于筛选状态的逗号分隔字符串（例如， |
|
| 可选。仅返回指定发票的支付意图。 |
|
| 可选。仅返回指定客户 ID 的支付意图。 |
|
| 可选。仅返回指定客户 DID 的支付意图。 |
|
| 可选。按特定的元数据键值对进行筛选。 |
|
| 可选。用于分页的页码，从 1 开始。默认为 |
|
| 可选。要返回的对象数量限制，介于 1 和 100 之间。默认为 |
返回值
一个分页对象，包含一个 PaymentIntent 对象列表和分页详情。
响应示例
{
"count": 15,
"list": [
{
"id": "pi_123456789",
"status": "succeeded",
// ... 其他属性
},
{
"id": "pi_987654321",
"status": "succeeded",
// ... 其他属性
}
// ... 更多支付意图
],
"paging": {
"page": 1,
"pageSize": 5
}
}搜索支付意图#
搜索与特定查询匹配的支付意图。
搜索支付意图
const results = await payment.paymentIntents.search({
query: 'cus_xxxxxxxx'
});
console.log(results);参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 搜索查询字符串。 |
|
| 可选。用于分页的页码，从 1 开始。默认为 |
|
| 可选。每页的项目数。默认为 |
返回值
一个分页对象，其中包含与搜索查询匹配的 PaymentIntent 对象列表。
响应示例
{
"count": 1,
"list": [
{
"id": "pi_123456789",
"customer_id": "cus_xxxxxxxx",
// ... 其他属性
}
],
"paging": {
"page": 1,
"pageSize": 20
}
}退款#
当支付意图成功后，您可以为该笔费用创建退款。这将创建一个 Refund 对象并尝试撤销该笔费用。
退款
const refund = await payment.paymentIntents.refund(
'pi_123456789',
{
amount: '500',
reason: 'requested_by_customer',
description: 'Refund for item not received.'
}
);
console.log(refund);参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 要退款的支付意图的 ID。 |
|
| 必填。 一个正数字符串，表示要退还此笔费用的金额。最多可退还原始费用的总金额。 |
|
| 必填。 表明退款原因的字符串。有效值为： |
|
| 必填。 对退款的解释。 |
返回值
返回一个新的 Refund 对象。
响应示例
{
"id": "re_abcdef123",
"type": "refund",
"livemode": false,
"amount": "500",
"description": "Refund for item not received.",
"status": "pending",
"reason": "requested_by_customer",
"currency_id": "cur_xxxxxxxx",
"customer_id": "cus_xxxxxxxx",
"payment_intent_id": "pi_123456789",
// ... 其他退款属性
}