付款連結 | 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 物件。

回應

{
  "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 物件，其中包含有關訂單項目及其相關價格和產品的擴充詳細資訊。

回應

{
  "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 物件。

回應

{
  "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。

回應

{
  "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。

回應

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx"
}