支払いリンク

支払いリンクは、製品やサービスを販売するための共有可能で再利用可能なページです。特定の製品と価格のセットに対してリンクを作成し、さまざまなチャネルを通じて複数の顧客と共有できます。これにより、完全なチェックアウトフローを構築することなく、迅速かつ簡単に支払いを回収できます。

支払いリンクオブジェクト

支払いリンクオブジェクトには、顧客に支払いページを提示するために必要なすべての情報が含まれています。以下にその主要な属性をいくつか示します。

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	3文字の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	必須。支払い後のNFTミントを有効にするには `true` に設定します。
`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。
`...`		2番目の引数は、更新するフィールドを含むオブジェクトです。`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	`submit_type` が `donate` である支払いリンクを除外するには `'hide'` に設定します。
`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"
}