支付链接 | ArcBlock

支付链接是一个可共享、可重复使用的页面，用于销售产品或服务。您可以为一组特定的产品和价格创建一个链接，并通过各种渠道与多个客户共享。这样无需构建完整的结账流程，即可快速便捷地收款。

支付链接对象

支付链接对象包含向客户展示支付页面所需的所有信息。以下是其一些关键属性：

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"
}