支付链接

支付链接是一个可共享、可重复使用的页面，用于销售产品或服务。您可以为一组特定的产品和价格创建一个链接，并通过各种渠道与多个客户共享。这样无需构建完整的结账流程，即可快速便捷地收款。
支付链接对象#支付链接对象包含向客户展示支付页面所需的所有信息。以下是其一些关键属性：
Attribute
Type
Description
id
string
支付链接对象的唯一标识符。
url
string
支付页面的 URL。客户可以重定向到此 URL 进行支付。
active
boolean
支付链接当前是否处于活动状态，可用于支付。
line_items
array
将要购买的产品和价格列表。
after_completion
object
购买完成后的行为，例如重定向到 URL 或显示确认消息。
allow_promotion_codes
boolean
在支付页面上启用优惠码。
currency_id
string
三字母 ISO 货币代码。
metadata
object
可以附加到对象上的一组键值对。用于存储附加信息。
created_at
string
对象创建时的时间戳。
创建支付链接#创建一个新的支付链接。
创建支付链接
const paymentLink = await payment.paymentLinks.create({
  line_items: [
    {
      price_id: 'price_xxxxxxxxxxxxxx',
      quantity: 1,
      adjustable_quantity: {
        enabled: true,
        minimum: 1,
        maximum: 10,
      },
    },
  ],
  after_completion: {
    type: 'hosted_confirmation',
    hosted_confirmation: {
      custom_message: 'Thanks for your purchase!',
    },
  },
  metadata: {
    order_id: '6735',
  },
});
参数#Name
Type
Description
line_items
array
必填。 订单项对象列表，每个对象代表要购买的产品。详见下文。
name
string
支付链接的可选内部名称。
lookup_key
string
一个可选的唯一字符串，可用于检索支付链接。
currency_id
string
此支付链接的货币 ID。如果未提供，则使用默认货币。
after_completion
object
指定成功支付后的行为。详见下文。
allow_promotion_codes
boolean
设置为 true 以允许兑换优惠码。默认为 false。
consent_collection
object
配置促销和用户服务条款的同意收集。详见下文。
nft_mint_settings
object
支付完成后铸造 NFT 的设置。详见下文。
metadata
object
一组用于存储附加信息的键值对。
line_items 对象属性
Name
Type
Description
price_id
string
必填。 价格对象的 ID。
quantity
number
必填。 正在购买的产品的数量。必须至少为 1。
adjustable_quantity
object
允许客户在支付页面上调整此订单项数量的配置。详见下文。
line_items.adjustable_quantity 对象属性
Name
Type
Description
enabled
boolean
必填。 设置为 true 以允许调整数量。
minimum
number
客户可选择的最小数量。必须大于或等于 0。
maximum
number
客户可选择的最大数量。必须大于 minimum。
after_completion 对象属性
Name
Type
Description
type
string
必填。 完成行为的类型。可以是 hosted_confirmation 或 redirect。
hosted_confirmation
object
向客户显示托管的确认消息。当 type 为 hosted_confirmation 时使用。
redirect
object
将客户重定向到特定 URL。当 type 为 redirect 时使用。
after_completion.hosted_confirmation 对象属性
Name
Type
Description
custom_message
string
向客户显示的可选自定义消息。最多 200 个字符。
after_completion.redirect 对象属性
Name
Type
Description
url
string
将客户重定向到的 URL。最多 2048 个字符。
consent_collection 对象属性
Name
Type
Description
promotions
string
确定如何处理促销通信的同意。可以是 none、opt_in 或 opt_out。
terms_of_service
string
确定如何处理服务条款的同意。可以是 none、opt_in 或 opt_out。
nft_mint_settings 对象属性
Name
Type
Description
enabled
boolean
必填。 设置为 true 以在支付后启用 NFT 铸造。
factory
string
用于铸造 NFT 的工厂地址。如果 enabled 为 true，则为必填项。
返回#如果创建成功，则返回一个 TPaymentLinkExpanded 对象。
Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ],
  "after_completion": {
    "type": "hosted_confirmation",
    "hosted_confirmation": {
      "custom_message": "Thanks for your purchase!"
    }
  },
  "metadata": {
    "order_id": "6735"
  }
}
检索支付链接#检索现有支付链接的详细信息。
检索支付链接
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);
参数#Name
Type
Description
id
string
必填。 要检索的支付链接的唯一标识符或 lookup_key。
返回#返回一个 TPaymentLinkExpanded 对象，其中包含有关订单项及其相关价格和产品的展开详细信息。
Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "price": {
        "id": "price_xxxxxxxxxxxxxx",
        "product_id": "prod_yyyyyyyyyyyyyy",
        "unit_amount": "10.00",
        "product": {
          "id": "prod_yyyyyyyyyyyyyy",
          "name": "My Awesome Product"
        }
      }
    }
  ]
}
更新支付链接#通过设置所传递参数的值来更新支付链接。任何未提供的参数将保持不变。请注意，您不能更新已归档的支付链接。
更新支付链接
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const updatedPaymentLink = await payment.paymentLinks.update(paymentLinkId, {
  active: false,
  metadata: {
    order_id: '6735-updated'
  }
});
参数#Name
Type
Description
id
string
必填。 要更新的支付链接的 ID。
...

第二个参数是包含要更新字段的对象。它支持许多与创建方法相同的参数，例如 active、line_items、metadata 和 after_completion。所有字段都是可选的。
返回#返回更新后的 TPaymentLink 对象。
Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "metadata": {
    "order_id": "6735-updated"
  }
}
列出所有支付链接#返回您的支付链接列表。
列出支付链接
const paymentLinks = await payment.paymentLinks.list({
  active: true,
  limit: 5
});
参数#Name
Type
Description
active
boolean
筛选列表以仅包括活动或非活动的支付链接。
donation
string
设置为 'hide' 以排除 submit_type 为 donate 的支付链接。
page
number
用于分页的页码。默认为 1。
pageSize
number
每页返回的对象数量。默认为 20。
order
string
结果的排序顺序。例如，'created_at:DESC'。
返回#返回一个分页对象，其中包含一个 TPaymentLinkExpanded 对象的 list。
Response
{
  "count": 15,
  "list": [
    {
      "id": "plink_xxxxxxxxxxxxxx",
      "active": true
    },
    {
      "id": "plink_yyyyyyyyyyyyyy",
      "active": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
归档支付链接#停用支付链接，使其无法用于支付。此操作可通过将 active 属性更新为 true 来撤销。
归档支付链接
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const archivedPaymentLink = await payment.paymentLinks.archive(paymentLinkId);
参数#Name
Type
Description
id
string
必填。 要归档的支付链接的 ID。
返回#返回已归档的 TPaymentLink 对象，其 active 属性设置为 false。
Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx"
}

概述

快速入门

SDK 结构

环境

核心概念

API 参考

支付链接

支付链接对象#

创建支付链接#

参数#

返回#

检索支付链接#

参数#

返回#

更新支付链接#

参数#

返回#

列出所有支付链接#

参数#

返回#

归档支付链接#

参数#

返回#

支付意图

支付方式

Attribute	Type	Description
`id`	string	支付链接对象的唯一标识符。
`url`	string	支付页面的 URL。客户可以重定向到此 URL 进行支付。
`active`	boolean	支付链接当前是否处于活动状态，可用于支付。
`line_items`	array	将要购买的产品和价格列表。
`after_completion`	object	购买完成后的行为，例如重定向到 URL 或显示确认消息。
`allow_promotion_codes`	boolean	在支付页面上启用优惠码。
`currency_id`	string	三字母 ISO 货币代码。
`metadata`	object	可以附加到对象上的一组键值对。用于存储附加信息。
`created_at`	string	对象创建时的时间戳。

Name	Type	Description
`line_items`	array	必填。订单项对象列表，每个对象代表要购买的产品。详见下文。
`name`	string	支付链接的可选内部名称。
`lookup_key`	string	一个可选的唯一字符串，可用于检索支付链接。
`currency_id`	string	此支付链接的货币 ID。如果未提供，则使用默认货币。
`after_completion`	object	指定成功支付后的行为。详见下文。
`allow_promotion_codes`	boolean	设置为 `true` 以允许兑换优惠码。默认为 `false`。
`consent_collection`	object	配置促销和用户服务条款的同意收集。详见下文。
`nft_mint_settings`	object	支付完成后铸造 NFT 的设置。详见下文。
`metadata`	object	一组用于存储附加信息的键值对。

Name	Type	Description
`price_id`	string	必填。价格对象的 ID。
`quantity`	number	必填。正在购买的产品的数量。必须至少为 1。
`adjustable_quantity`	object	允许客户在支付页面上调整此订单项数量的配置。详见下文。

Name	Type	Description
`enabled`	boolean	必填。设置为 `true` 以允许调整数量。
`minimum`	number	客户可选择的最小数量。必须大于或等于 0。
`maximum`	number	客户可选择的最大数量。必须大于 `minimum`。

Name	Type	Description
`type`	string	必填。完成行为的类型。可以是 `hosted_confirmation` 或 `redirect`。
`hosted_confirmation`	object	向客户显示托管的确认消息。当 `type` 为 `hosted_confirmation` 时使用。
`redirect`	object	将客户重定向到特定 URL。当 `type` 为 `redirect` 时使用。

Name	Type	Description
`promotions`	string	确定如何处理促销通信的同意。可以是 `none`、`opt_in` 或 `opt_out`。
`terms_of_service`	string	确定如何处理服务条款的同意。可以是 `none`、`opt_in` 或 `opt_out`。

Name	Type	Description
`enabled`	boolean	必填。设置为 `true` 以在支付后启用 NFT 铸造。
`factory`	string	用于铸造 NFT 的工厂地址。如果 `enabled` 为 `true`，则为必填项。

Name	Type	Description
`id`	string	必填。要更新的支付链接的 ID。
`...`		第二个参数是包含要更新字段的对象。它支持许多与创建方法相同的参数，例如 `active`、`line_items`、`metadata` 和 `after_completion`。所有字段都是可选的。

Name	Type	Description
`active`	boolean	筛选列表以仅包括活动或非活动的支付链接。
`donation`	string	设置为 `'hide'` 以排除 `submit_type` 为 `donate` 的支付链接。
`page`	number	用于分页的页码。默认为 `1`。
`pageSize`	number	每页返回的对象数量。默认为 `20`。
`order`	string	结果的排序顺序。例如，`'created_at:DESC'`。