カスタムフィールドを追加する

Checkout で構築済みの決済ページにさらにフィールドを追加します。

決済フォームにカスタムフィールドを追加すると、顧客から追加情報を収集できます。この情報は、支払いの完了後に使用できるようになり、購入のフルフィルメントに利用できます。

カスタムフィールドには以下の制限があります。

フィールドは 3 つまで使用できます。
setup モードでは使用できません。
テキストフィールドで対応できるのは 255 文字までです。
数値フィールドは、最大 255 桁に対応できます。
ドロップダウンフィールドでは最大 200 件のオプションを使用できます。

注意

カスタムフィールドは、個人情報、保護対象のデータ、機密データ、法律によって制限されている情報の収集には使用しないでください。

Checkout セッションを作成する

カスタムフィールドの配列を指定する際に、Checkout セッションを作成します。各フィールドには、実装でフィールドの照合に使用する一意の key が必要です。また、顧客に表示するフィールドのラベルも指定してください。カスタムフィールドのラベルは翻訳されませんが、locale パラメーターを使用して、Checkout セッションの言語をラベルの言語に一致させることができます。

カスタムフィールドを取得する

顧客が Checkout セッションを完了すると、フィールドが入力されたことを示す checkout.session.completed Webhook が送信されます。

以下に checkout.session.completed ペイロードの例を示します。

{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1664928000,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session",
      "custom_fields": [{
        "key": "engraving",
        "label": {
          "type": "custom",
          "custom": "Personalized engraving"
        },
        "optional": false,
        "type": "text",
        "text": {
          "value": "Jane",
        }
      }],
      "mode": "payment",
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}

カスタムフィールドを使用する

フィールドにオプションのマークを付ける

デフォルトでは、顧客は、支払いを完了する前に、すべてのフィールドに入力する必要があります。フィールドにオプションのマークを付けるには、optional=true を渡します。

ドロップダウンフィールドに、選択するオプションのリストが顧客に表示されます。ドロップダウンフィールドを作成するには、type=dropdown とオプションのリストを指定し、それぞれにlabel と value を指定します。label は顧客に表示され、実装では、value を使用して、顧客が選択したオプションを照合します。

数値のみのフィールドを追加する

数値のみのフィールドは、255 桁までの数値のみを受け付けるテキストフィールドを顧客に提供します。数値のみのフィールドを作成するには、type=numeric を指定します。

サブスクリプションのカスタムフィールドを取得する

subscription パラメーターを使用して作成した Checkout セッションのクエリを実行することで、サブスクリプションに関連付けられているカスタムフィールドを取得できます。

文字数の検証を追加する

必要に応じて text フィールドタイプと numeric フィールドタイプの最小文字数と最大文字数の要件を指定できます。

デフォルト値を追加する

必要に応じて、テキスト、数値、およびドロップダウンフィールドタイプのデフォルト値を指定できます。デフォルト値は、支払いページに事前入力されています。