API 参考

支付链接

支付链接允许你为你的产品或服务创建一个可分享的、托管的支付页面。这是一种无需编写任何前端代码即可在线销售的简单方法。本节详细介绍如何使用 SDK 创建和管理支付链接。
如需了解有关支付链接所含项目的更多信息，请参阅产品与价格文档。
支付链接对象#PaymentLink 对象包含向客户展示支付页面所需的所有信息。以下是其一些关键属性：
属性
类型
描述
id
string
支付链接的唯一标识符。
active
boolean
支付链接当前是否有效，可用于支付。
name
string
支付链接的内部名称，对客户不可见。
line_items
Array<Object>
待售商品。每个对象必须包含 price_id 和 quantity。
currency_id
string
三字母 ISO 货币代码。
after_completion
Object
支付成功后的行为。可以是 redirect 到某个 URL，也可以是 hosted_confirmation 页面。
allow_promotion_codes
boolean
切换客户是否可以应用促销代码。
custom_fields
Array<Object>
从客户处收集的自定义字段列表。
billing_address_collection
string
指定是否收集客户的账单地址。可以是 'auto' 或 'required'。
metadata
Object
可附加到对象上的一组键值对。可用于存储附加信息。

创建支付链接#创建新的支付链接。
参数#名称
类型
描述
name
string
必需。 支付链接的内部名称。
currency_id
string
必需。 支付所用的货币。
line_items
Array<Object>
必需。 待购商品列表。每个商品都是一个包含 price_id (字符串) 和 quantity (数字) 的对象。
active
boolean
链接是否有效。默认为 true。
after_completion
Object
定义支付成功后的操作。设置为 { "type": "redirect", "redirect": { "url": "https://yoursite.com/success" } } 可重定向客户。
allow_promotion_codes
boolean
启用或禁用促销代码。默认为 false。
billing_address_collection
string
设置为 'required' 可始终收集客户的账单地址。默认为 'auto'。
custom_fields
Array<Object>
从客户处收集自定义信息。有关对象结构，请参见 CustomField 类型。
metadata
Record<string, any>
与支付链接关联的键值数据。
返回值#调用成功，返回 PaymentLink 对象。
示例#async function createPaymentLink() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      name: 'Monthly Subscription Box',
      currency_id: 'usd',
      line_items: [
        {
          price_id: 'price_12345',
          quantity: 1,
        },
      ],
      after_completion: {
        type: 'redirect',
        redirect: {
          url: 'https://example.com/thanks',
        },
      },
      metadata: {
        order_id: '6735',
      },
    });
    console.log(paymentLink);
  } catch (error) {
    console.error('创建支付链接时出错：', error);
  }
}

createPaymentLink();响应示例#{
  "id": "pl_abc123",
  "active": true,
  "livemode": false,
  "name": "Monthly Subscription Box",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "currency_id": "usd",
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com/thanks"
    }
  },
  "allow_promotion_codes": false,
  "custom_fields": [],
  "customer_creation": "if_required",
  "billing_address_collection": "auto",
  "submit_type": "auto",
  "metadata": {
    "order_id": "6735"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
检索支付链接#检索现有支付链接的详细信息。
参数#名称
类型
描述
id
string
必需。 要检索的支付链接的 ID。
返回值#返回一个 PaymentLink 对象，但 line_items 等关联资源会被展开。
示例#async function retrievePaymentLink(paymentLinkId) {
  try {
    const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);
    console.log(paymentLink);
  } catch (error) {
    console.error('检索支付链接时出错：', error);
  }
}

retrievePaymentLink('pl_abc123');响应示例#{
  "id": "pl_abc123",
  "active": true,
  "livemode": false,
  "name": "Monthly Subscription Box",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "currency_id": "usd",
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com/thanks"
    }
  },
  "allow_promotion_codes": false,
  "custom_fields": [],
  "customer_creation": "if_required",
  "billing_address_collection": "auto",
  "submit_type": "auto",
  "metadata": {
    "order_id": "6735"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
更新支付链接#通过设置所传递参数的值来更新支付链接。
参数#名称
类型
描述
id
string
必需。 要更新的支付链接的 ID。
data
Object
必需。 一个包含要更新字段的对象。你可以更新 active、metadata 或 line_items 等字段。
返回值#返回更新后的 PaymentLink 对象。
示例#async function updatePaymentLink(paymentLinkId) {
  try {
    const updatedLink = await payment.paymentLinks.update(paymentLinkId, {
      metadata: { order_id: '6735-updated' },
      active: false
    });
    console.log(updatedLink);
  } catch (error) {
    console.error('更新支付链接时出错：', error);
  }
}

updatePaymentLink('pl_abc123');响应示例#{
  "id": "pl_abc123",
  "active": false,
  "metadata": {
    "order_id": "6735-updated"
  }
}
归档支付链接#归档支付链接，使其失效。此操作等同于使用 active: false 更新链接。
参数#名称
类型
描述
id
string
必需。 要归档的支付链接的 ID。
返回值#返回已归档的 PaymentLink 对象。
示例#async function archivePaymentLink(paymentLinkId) {
  try {
    const archivedLink = await payment.paymentLinks.archive(paymentLinkId);
    console.log('已归档：', archivedLink.active);
  } catch (error) {
    console.error('归档支付链接时出错：', error);
  }
}

archivePaymentLink('pl_abc123');响应示例#{
  "id": "pl_abc123",
  "active": false,
  "livemode": false,
  "name": "Monthly Subscription Box",
  "metadata": {
    "order_id": "6735-updated"
  },
  "updated_at": "2023-10-27T10:05:00.000Z"
}
列出所有支付链接#返回分页的支付链接列表。
参数#名称
类型
描述
page
number
分页的页码。默认为 1。
pageSize
number
每页的项目数。默认为 20。
order
Array<string>
用于指定排序顺序的数组，例如 ['created_at', 'DESC']。
starting_after
string
用于分页的游标。返回此 ID 之后的对象。
ending_before
string
用于分页的游标。返回此 ID 之前的对象。
返回值#返回一个分页对象，其中包含一个 PaymentLink 对象 list 和总数 count。
示例#async function listPaymentLinks() {
  try {
    const paymentLinks = await payment.paymentLinks.list({ pageSize: 5 });
    console.log(`找到 ${paymentLinks.count} 个链接。`);
    paymentLinks.list.forEach(link => {
      console.log(`- ${link.name} (ID: ${link.id})`);
    });
  } catch (error) {
    console.error('列出支付链接时出错：', error);
  }
}

listPaymentLinks();响应示例#{
  "count": 50,
  "list": [
    {
      "id": "pl_abc123",
      "name": "Monthly Subscription Box",
      "active": false
    },
    {
      "id": "pl_def456",
      "name": "One-Time Consultation",
      "active": true
    }
  ]
}借助这些工具，你可以通过编程方式管理支付链接。要了解如何使用支付链接发起客户购买，请参阅结账会话文档。

属性	类型	描述
`id`	`string`	支付链接的唯一标识符。
`active`	`boolean`	支付链接当前是否有效，可用于支付。
`name`	`string`	支付链接的内部名称，对客户不可见。
`line_items`	`Array<Object>`	待售商品。每个对象必须包含 `price_id` 和 `quantity`。
`currency_id`	`string`	三字母 ISO 货币代码。
`after_completion`	`Object`	支付成功后的行为。可以是 `redirect` 到某个 URL，也可以是 `hosted_confirmation` 页面。
`allow_promotion_codes`	`boolean`	切换客户是否可以应用促销代码。
`custom_fields`	`Array<Object>`	从客户处收集的自定义字段列表。
`billing_address_collection`	`string`	指定是否收集客户的账单地址。可以是 `'auto'` 或 `'required'`。
`metadata`	`Object`	可附加到对象上的一组键值对。可用于存储附加信息。

名称	类型	描述
`name`	`string`	必需。支付链接的内部名称。
`currency_id`	`string`	必需。支付所用的货币。
`line_items`	`Array<Object>`	必需。待购商品列表。每个商品都是一个包含 `price_id` (字符串) 和 `quantity` (数字) 的对象。
`active`	`boolean`	链接是否有效。默认为 `true`。
`after_completion`	`Object`	定义支付成功后的操作。设置为 `{ "type": "redirect", "redirect": { "url": "https://yoursite.com/success" } }` 可重定向客户。
`allow_promotion_codes`	`boolean`	启用或禁用促销代码。默认为 `false`。
`billing_address_collection`	`string`	设置为 `'required'` 可始终收集客户的账单地址。默认为 `'auto'`。
`custom_fields`	`Array<Object>`	从客户处收集自定义信息。有关对象结构，请参见 `CustomField` 类型。
`metadata`	`Record<string, any>`	与支付链接关联的键值数据。

名称	类型	描述
`id`	`string`	必需。要更新的支付链接的 ID。
`data`	`Object`	必需。一个包含要更新字段的对象。你可以更新 `active`、`metadata` 或 `line_items` 等字段。

名称	类型	描述
`page`	`number`	分页的页码。默认为 `1`。
`pageSize`	`number`	每页的项目数。默认为 `20`。
`order`	`Array<string>`	用于指定排序顺序的数组，例如 `['created_at', 'DESC']`。
`starting_after`	`string`	用于分页的游标。返回此 ID 之后的对象。
`ending_before`	`string`	用于分页的游标。返回此 ID 之前的对象。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

支付链接

支付链接对象#

创建支付链接#

参数#

返回值#

示例#

响应示例#

检索支付链接#

参数#

返回值#

示例#

响应示例#

更新支付链接#

参数#

返回值#

示例#

响应示例#

归档支付链接#

参数#

返回值#

示例#

响应示例#

列出所有支付链接#

参数#

返回值#

示例#

响应示例#

支付方式

结账会话