支付意图
支付意图（Payment Intent）是一个对象，代表您向客户收款的意图，并跟踪从创建到完成的整个支付过程的生命周期。它是 Payment Kit API 的核心部分，指导您完成确认和捕获支付所需的步骤。
大多数集成将使用结账会话来自动创建和处理支付意图。但是，您也可以使用此 API 来更直接地控制支付生命周期。
支付意图的生命周期#
一个支付意图从创建到完成会经历多种状态。理解此流程是有效管理支付的关键。
支付意图对象#
PaymentIntent 对象包含有关交易的详细信息。以下是其一些关键属性：
属性 | 类型 | 描述 |
|---|---|---|
|
| 支付意图的唯一标识符，前缀为 |
|
| 计划收取的金额。 |
|
| 三位字母的 ISO 货币代码（或自定义货币 ID）。 |
|
| 此支付意图所属客户的 ID（如果存在）。 |
|
| 支付意图的当前状态。可以是 |
|
| 定义支付如何被捕获。可以是 |
|
| 定义支付如何被确认。可以是 |
|
| 遇到的最后一个支付错误（如果有）。包含有关失败的详细信息。 |
|
| 您可以附加到对象的一组键值对。 |
|
| 支付意图创建时的时间戳。 |
创建支付意图#
创建一个新的支付意图。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 交易金额，为字符串格式。 |
|
| 必需。 支付的货币。 |
|
| 可选。与此支付关联的客户 ID。 |
|
| 可选。附加到对象的任意字符串。 |
|
| 可选。要附加到此 PaymentIntent 的 PaymentMethod 的 ID。 |
|
| 可选。此 PaymentIntent 允许使用的支付方式类型列表（例如 |
|
| 可选。控制资金何时被捕获。可以是 |
|
| 可选。用于存储附加信息的一组键值对。 |
返回
返回创建的 PaymentIntent 对象。
示例
async function createPaymentIntent() {
try {
const paymentIntent = await payment.paymentIntents.create({
amount: '2000',
currency_id: 'usd',
payment_method_types: ['stripe'],
description: 'Charge for services rendered',
});
console.log('已创建支付意图:', paymentIntent);
} catch (error) {
console.error('错误:', error.message);
}
}
createPaymentIntent();响应示例
{
"id": "pi_1J2a3b4c5d6e7f8g",
"livemode": false,
"description": "Charge for services rendered",
"amount": "2000",
"amount_received": "0",
"amount_capturable": "0",
"currency_id": "usd",
"customer_id": null,
"payment_method_id": null,
"status": "requires_payment_method",
"capture_method": "automatic",
"confirmation_method": "automatic",
"payment_method_types": [
"stripe"
],
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}检索支付意图#
检索现有支付意图的详细信息。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要检索的支付意图的唯一标识符。 |
返回
返回 PaymentIntent 对象，其中一些字段会展开为完整对象。
示例
async function retrievePaymentIntent(id) {
try {
const paymentIntent = await payment.paymentIntents.retrieve(id);
console.log('已检索支付意图:', paymentIntent.status);
} catch (error) {
console.error('错误:', error.message);
}
}
retrievePaymentIntent('pi_1J2a3b4c5d6e7f8g');响应示例
{
"id": "pi_1J2a3b4c5d6e7f8g",
"livemode": false,
"description": "Charge for services rendered",
"amount": "2000",
"status": "succeeded",
"currency_id": "usd",
"customer_id": "cus_a1b2c3d4e5f6",
// ... other fields
}更新支付意图#
更新支付意图对象的属性。您可以更新 metadata 或 description 等详细信息。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要更新的支付意图的 ID。 |
|
| 必需。 包含要更新字段的对象。 |
data 中的可更新字段
名称 | 类型 | 描述 |
|---|---|---|
|
| 附加到对象的任意字符串。 |
|
| 用于存储附加信息的一组键值对。 |
|
| 成功支付的收据将发送到的电子邮件地址。 |
返回
返回更新后的 PaymentIntent 对象。
示例
async function updatePaymentIntent(id) {
try {
const paymentIntent = await payment.paymentIntents.update(id, {
metadata: { order_id: '6735' }
});
console.log('已更新支付意图:', paymentIntent.metadata);
} catch (error) {
console.error('错误:', error.message);
}
}
updatePaymentIntent('pi_1J2a3b4c5d6e7f8g');响应示例
{
"id": "pi_1J2a3b4c5d6e7f8g",
"metadata": {
"order_id": "6735"
},
// ... other fields
}列出所有支付意图#
返回您的支付意图的分页列表。该列表可以通过各种参数进行筛选。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 可选。仅返回具有给定状态的支付意图。 |
|
| 可选。仅返回给定发票的支付意图。 |
|
| 可选。仅返回给定客户的支付意图。 |
|
| 可选。按自定义元数据字段筛选。 |
|
| 可选。用于分页的页码。 |
|
| 可选。每页的项目数（默认：20）。 |
|
| 可选。排序顺序（例如 |
返回
一个分页对象，包含 PaymentIntent 对象的 list 和总 count。
示例
async function listSuccessfulPayments() {
try {
const paymentIntents = await payment.paymentIntents.list({
status: 'succeeded',
pageSize: 10
});
console.log(`找到 ${paymentIntents.count} 个成功支付。`);
paymentIntents.list.forEach(pi => console.log(pi.id));
} catch (error) {
console.error('错误:', error.message);
}
}
listSuccessfulPayments();响应示例
{
"count": 42,
"list": [
{
"id": "pi_1J2a3b4c5d6e7f8g",
"status": "succeeded",
"amount": "2000",
// ... other fields
},
{
"id": "pi_zY9x8w7v6u5t4s3r",
"status": "succeeded",
"amount": "5000",
// ... other fields
}
]
}搜索支付意图#
根据查询字符串对支付意图执行自由文本搜索。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 搜索查询。 |
|
| 可选。用于分页的页码。 |
|
| 可选。每页的项目数（默认：20）。 |
返回
一个分页对象，包含匹配的 PaymentIntent 对象的 list 和总 count。
示例
async function searchPayments(query) {
try {
const results = await payment.paymentIntents.search({ query: query });
console.log(`为 '${query}' 找到 ${results.count} 个结果。`);
} catch (error) {
console.error('错误:', error.message);
}
}
searchPayments('order_id:6735');响应示例
{
"count": 1,
"list": [
{
"id": "pi_1J2a3b4c5d6e7f8g",
"status": "succeeded",
"metadata": {
"order_id": "6735"
},
// ... other fields
}
]
}退款支付意图#
为已扣款的支付意图创建一个退款对象。这可以是全额或部分退款。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必需。 要退款的支付意图的 ID。 |
|
| 必需。 包含退款详情的对象。 |
data 中的字段
名称 | 类型 | 描述 |
|---|---|---|
|
| 可选。要退款的金额。如果未提供，则全额退款。 |
|
| 可选。退款原因。可以是 |
|
| 可选。关于退款的内部备注。 |
返回
返回一个展开的 Refund 对象。
示例
async function refundPayment(id) {
try {
const refund = await payment.paymentIntents.refund(id, {
amount: '500',
reason: 'requested_by_customer',
description: 'Customer requested partial refund.'
});
console.log('已处理退款:', refund.id);
} catch (error) {
console.error('错误:', error.message);
}
}
refundPayment('pi_1J2a3b4c5d6e7f8g');响应示例
{
"id": "re_a1b2c3d4e5f6g7h8",
"amount": "500",
"currency_id": "usd",
"payment_intent_id": "pi_1J2a3b4c5d6e7f8g",
"reason": "requested_by_customer",
"status": "succeeded",
"created_at": "2023-10-27T12:00:00.000Z",
// ... other fields
}现在您已了解如何使用支付意图管理支付生命周期，您可能希望更详细地了解 Refunds API 或学习如何创建可重复使用的支付链接。