# カスタムコンポーネントで決済を拡張

カスタムテキストを表示し、Checkout Sessions に関する追加情報を収集します。

# ホスト型ページ

> This is a ホスト型ページ for when platform is web and payment-ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=stripe-hosted.

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

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

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

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

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

### Checkout Session を作成する

[カスタムフィールド](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields)の配列を指定する際に、Checkout セッションを作成します。各フィールドには、実装でフィールドの照合に使用する一意の `key` が必要です。また、顧客に表示するフィールドのラベルも指定してください。カスタムフィールドのラベルは翻訳されませんが、[locale](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) パラメーターを使用して、Checkout セッションの言語をラベルの言語に一致させることができます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text"
```
![](https://d37ugbyn3rpeym.cloudfront.net/videos/checkout/custom_fields_embedded.mov)
### カスタムフィールドを取得する

顧客が Checkout セッションを完了すると、フィールドが入力されたことを示す [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) が送信されます。

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

```json
{
  "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"
}
```

ダッシュボードからカスタムフィールドの値を検索および編集することもできます。そのためには、[取引](https://dashboard.stripe.com/payments)タブで特定の支払いをクリックするか、[ダッシュボード](https://dashboard.stripe.com/payments)から支払いをエクスポートするときにカスタムフィールド値を含めます。

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

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

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][optional]=true"
```
![](https://b.stripecdn.com/docs-statics-srv/assets/optional.bf0c1564296ff02264bd5e8c066a6034.png)

#### ドロップダウンフィールドを追加する

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=sample" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Free sample" \
  -d "custom_fields[0][optional]=true" \
  -d "custom_fields[0][type]=dropdown" \
  -d "custom_fields[0][dropdown][options][0][label]=Balm sample" \
  -d "custom_fields[0][dropdown][options][0][value]=balm" \
  -d "custom_fields[0][dropdown][options][1][label]=BB cream sample" \
  -d "custom_fields[0][dropdown][options][1][value]=cream"
```
![ドロップダウンフィールドが設定された決済ページ](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

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

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=invoice" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Invoice number" \
  -d "custom_fields[0][type]=numeric"
```

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

[subscription](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) パラメーターを使用して作成した Checkout セッションのクエリを実行することで、サブスクリプションに関連付けられているカスタムフィールドを取得できます。

```curl
curl -G https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "subscription={{SUBSCRIPTION_ID}}"
```

#### 文字数の検証を追加する

必要に応じて `text` フィールドタイプと `numeric` フィールドタイプの最小文字数と最大文字数の[要件](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length)を指定できます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][minimum_length]=10" \
  -d "custom_fields[0][text][maximum_length]=20" \
  -d "custom_fields[0][optional]=true"
```
![字数制限が設定されたフィールド](https://b.stripecdn.com/docs-statics-srv/assets/between-validation.20431cd8e0c03a028843945d1f1ea314.png)

#### デフォルト値を追加する

必要に応じて、[テキスト](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value)、[数値](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value)、および[ドロップダウン](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value)フィールドタイプのデフォルト値を指定できます。デフォルト値は、支払いページに事前入力されています。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][default_value]=Stella" \
  -d "custom_fields[1][key]=size" \
  -d "custom_fields[1][label][type]=custom" \
  -d "custom_fields[1][label][custom]=Size" \
  -d "custom_fields[1][type]=dropdown" \
  -d "custom_fields[1][dropdown][default_value]=small" \
  -d "custom_fields[1][dropdown][options][0][value]=small" \
  -d "custom_fields[1][dropdown][options][0][label]=Small" \
  -d "custom_fields[1][dropdown][options][1][value]=large" \
  -d "custom_fields[1][dropdown][options][1][label]=Large"
```

## テキストとポリシーをカスタマイズする

顧客が Stripe Checkout を使用して支払う場合は、出荷予定日や処理時間などの追加テキストを表示できます。

> Checkout 上に生成された Stripe のテキスト、Stripe との契約上の義務、Stripe のポリシー、その他適用法に違反する、または誤解を生じさせるカスタムテキストを、この機能を使用して作成することは禁止されています。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  --data-urlencode "success_url=https://example.com/success"
```
![配送先住所の収集の近くにあるカスタムテキスト](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

配送先住所の収集フィールドの近くにあるカスタムテキスト
![支払うボタンの上に表示されるカスタムテキスト](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

**支払う**ボタンの上に表示されるカスタムテキスト
![支払うボタンの下に表示されるカスタムテキスト](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

**支払う**ボタンの後に表示されるカスタムテキスト

カスタムテキストは 1200 文字以内で設定できます。ただし、Stripe Checkout はコンバージョンを最適化するため、その他の情報を追加するとコンバージョン率に影響する場合があります。[マークダウン構文](https://www.markdownguide.org/cheat-sheet/)を使用してテキストを太字にしたり、リンクを挿入することができます。

### 送信ボタンをカスタマイズする

Checkout がお客様のビジネスモデルに適合するように、1 回限りの購入に対する Checkout の送信ボタンに表示されるテキストを設定できます。

Session の `submit_type` を定義します。この例 (5 USD の寄付の場合) では、カスタマイズした Checkout 送信ボタンに **$5.00 の寄付** と表示されます。`submit_type` オプションの完全なリストについては、[API リファレンス](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type)を参照してください。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d submit_type=donate \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success"
```

## ローカリゼーションとサポート対象言語

Checkout は顧客のブラウザーのロケールをデフォルトで検出し、Stripe がその言語を[サポートしている](https://support.stripe.com/questions/supported-languages-for-stripe-checkout)場合は、翻訳版のページを表示します。Checkout セッションの作成時に `locale` [パラメーター](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale)を渡すことで、Checkout のブラウザーのロケールを上書きできます。

Checkout は、数字と通貨の形式の設定にもロケールを使用します。たとえば、価格が EUR で、ロケールが `auto` に設定された商品を販売する際、英語 (`en`) を使用するように設定されたブラウザーでは €25.00 と表示され、ドイツ語 (`de`) を使用するように設定されたブラウザーでは 25,00 € と表示されます。

### ポリシーと連絡先情報をカスタマイズする

Checkout では、返品、返金、リーガルポリシーおよびサポートの連絡先情報を顧客に表示できます。[Checkout の設定](https://dashboard.stripe.com/settings/checkout)に移動して、以下のような表示情報を設定できます。

- 返品および返金に関するポリシーの詳細
- サポートの電話番号、メールアドレス、および Web サイト
- 利用規約およびプライバシーポリシーへのリンク

この情報を提示することで、買い手の信頼を高め、カート離脱率を最小化できます。

### サポートおよびリーガルポリシーの設定

[Checkout の設定](https://dashboard.stripe.com/settings/checkout)で、**連絡先情報**を有効にして、サポートの連絡先情報をセッションに追加します。同様に、**リーガルポリシー**を選択して、**利用規約**と**プライバシーポリシー**へのリンクをセッションに追加します。顧客が決済フローを完了する際に、リーガルポリシーに黙示的に同意するように求める場合は、**規約への同意を表示**というチェックボックスを選択します。

[公開情報の設定](https://dashboard.stripe.com/settings/public)で、サポートの連絡先情報とリーガルポリシーへのリンクを追加する必要があります。

以下のプレビューは、サポートの連絡先情報、ストアのリーガルポリシーへのリンク、および支払い条件に関する情報が記載されたダイアログが、Checkout の画面にどのように表示されるかを示しています。
![連絡先情報が記載された決済ページです。](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Checkout の連絡先情報のプレビュー
![リーガルポリシーが記載された決済ページです。](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Checkout のリーガルポリシーのプレビュー

### 返品および返金に関するポリシーの設定

**返品および返金に関するポリシー**を有効にして、返品、返金、または交換に関するポリシーを表示します。物品を販売するビジネスは、返品に関するポリシーを使用しますが、デジタル商品またはカスタマイズされた物品を販売するビジネスは通常、返金に関するポリシーを使用します。これらは併記可能であるため、ビジネスが双方のカテゴリの商品を販売している場合は、両方のオプションを選択できます。以下のような返品と返金の詳細を編集できます。

- 返品、返金、交換を受け入れるかどうか
- 返品、返金、交換が無償であるか、または手数料が課せられるか
- 返品、返金、交換を受け入れるのは、購入後何日間か
- 顧客が配送されたアイテムを返品する方法
- 実店舗での返品は可能かどうか
- 返品および返金に関するポリシー全文へのリンク
- カスタムメッセージ

無料の返品、返金、交換を受け入れている場合、Checkout はこのポリシーを顧客に強調表示します。

以下のプレビューは、返品に関するポリシーが Checkout でどのように表示されるかを示しています。この例では、60 日以内の返送または実店舗での全額返金 (または交換) に対応している購入に関するものです。返金に対しても同様の情報を表示できます。
![Checkout の返品に関するポリシーのプレビュー](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Checkout の返品に関するポリシーのプレビュー
![Checkout のポリシーハイライトのプレビュー](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Checkout のポリシーハイライトのプレビュー。

#### 利用規約への同意を得る

ビジネスでは、顧客が支払いを行う前に利用規約への同意を求めることがよくあります。これは、商品またはサブスクリプションのタイプによって異なります。Checkout では、支払いの前に顧客に利用規約への同意を求めて必要な契約書を収集することができます。
![利用規約への同意を得る](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

利用規約への同意を得る

セッションを作成する際に、Stripe Checkout で利用規約への同意を得ることができます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=2" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "consent_collection[terms_of_service]=required" \
  --data-urlencode "custom_text[terms_of_service_acceptance][message]=I agree to the [Terms of Service](https://example.com/terms)"
```

`consent_collection.terms_of_service='required'` の場合、Checkout に利用規約への同意を収集するためのチェックボックスが動的に表示されます。`consent_collection.terms_of_service='none'` の場合、Checkout にチェックボックスは表示されず、また顧客に利用規約への同意が求められることもありません。利用規約への同意を求める前に、ビジネスの[公開情報](https://dashboard.stripe.com/settings/public)に利用規約の URL を設定してください。プライバシーポリシーの URL の設定は任意です。[公開情報](https://dashboard.stripe.com/settings/public)でプライバシーポリシーの URL が設定されている場合、Checkout にもプライバシーポリシーへのリンクが表示されます。

顧客が決済フローを完了した後、`checkout.session.completed` Webhook の Session オブジェクトを確認するか、API を使用して Session を取得することで、顧客が利用規約に同意したことを確認できます。利用規約が承認されると、Session の [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) フィールドは `accepted` に設定されます。

`custom_text.terms_of_service_acceptance` を使用して、チェックボックスの横に表示されるテキストをカスタマイズできます。`consent_collection.terms_of_service='required'` を設定する必要があります。独自の用語を使用する際は、マークダウンリンクを挿入します。例: `I agree to the [Terms of Service](https://example.com/terms)`

> このテキストに変更を加える前に、弁護士およびコンプラインスアドバイザーと相談することをお勧めします。Checkout 上に生成された Stripe のテキスト、Stripe との契約上の義務、Stripe のポリシー、その他適用法に違反する、または誤解を生じさせるカスタムテキストは、この機能を使用して表示することはできません。

#### プロモーションメールへの同意を収集する

プロモーションメールを送信して、顧客に新製品について知らせたり、クーポンや割引を案内したりできます。これを行う前に、プロモーションメールを受信するための[同意を得る](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md)必要があります。

## 決済手段の再利用規約とサブスクリプション規約をカスタマイズする

セッションが `setup` または `subscription` モードの場合、あるいは `setup_future_usage` が設定された `payment` モードの場合、Checkout は顧客の決済手段の再利用に関するメッセージを表示します。メッセージには、選択された決済手段に固有の情報を含めることができます。デフォルトのテキストは非表示にしたりカスタマイズしたりできますが、決済手段固有のテキストはできません。

サブスクリプションの場合、カスタムテキストには次の情報を含めることができます。

- サブスクリプション規約へのリンク
- カスタマーポータルへのリンク
- キャンセルの手順とポリシー
![サブスクリプションモードにおけるデフォルトの決済手段の再利用規約の表示](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

サブスクリプションモードにおけるデフォルトの決済手段の再利用規約

> このテキストをカスタマイズすることで、お客様には規制遵守の責任が生じます。たとえば、カードネットワークのルールや地域の規制に変更が生じた場合、適宜テキストを更新しなければなりません。この機能を使用する場合は必ず、会社の法務チームに相談するか、決済手段の再利用に関する情報を含むカスタムテキストを設定してください。カスタマイズしたテキストが、サポート予定のすべてのモードに対応していることを確認してください。

決済手段の再利用規約のテキストを非表示にするには、`consent_collection.payment_method_reuse_agreement.position='hidden'` を設定します。Checkout では、決済手段の再利用について記述するデフォルトのテキストは表示されなくなります。Stripe のデフォルトテキストの代わりに自分でテキストを設定するには、`custom_text.after_submit.message` を設定します。`custom_text.submit` または `custom_text.terms_of_service_acceptance` を使用して、自分で設定したテキストを表示することもできます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  --data-urlencode "success_url=https://example.com/success" \
  -d "consent_collection[payment_method_reuse_agreement][position]=hidden" \
  --data-urlencode "custom_text[after_submit][message]=You can cancel your subscription at any time by [logging into your account](https://www.example.com/)"
```


# 埋め込み型ページ

> This is a 埋め込み型ページ for when platform is web and payment-ui is embedded-form. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=embedded-form.

決済フォームにカスタムフィールドを追加して、顧客から追加情報を収集することができます。また、顧客に表示されるテキストや Checkout ポリシーの表示をカスタマイズすることもできます。

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

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

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

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

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

### Checkout Session を作成する

[カスタムフィールド](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields)の配列を指定する際に、Checkout セッションを作成します。各フィールドには、実装でフィールドの照合に使用する一意の `key` が必要です。また、顧客に表示するフィールドのラベルも指定してください。カスタムフィールドのラベルは翻訳されませんが、[locale](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) パラメーターを使用して、Checkout セッションの言語をラベルの言語に一致させることができます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text"
```
![](https://d37ugbyn3rpeym.cloudfront.net/videos/checkout/custom_fields_embedded.mov)
### カスタムフィールドを取得する

顧客が Checkout セッションを完了すると、フィールドが入力されたことを示す [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) が送信されます。

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

```json
{
  "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"
}
```

ダッシュボードからカスタムフィールドの値を検索および編集することもできます。そのためには、[取引](https://dashboard.stripe.com/payments)タブで特定の支払いをクリックするか、[ダッシュボード](https://dashboard.stripe.com/payments)から支払いをエクスポートするときにカスタムフィールド値を含めます。

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

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

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][optional]=true"
```
![](https://b.stripecdn.com/docs-statics-srv/assets/optional.bf0c1564296ff02264bd5e8c066a6034.png)

#### ドロップダウンフィールドを追加する

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=sample" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Free sample" \
  -d "custom_fields[0][optional]=true" \
  -d "custom_fields[0][type]=dropdown" \
  -d "custom_fields[0][dropdown][options][0][label]=Balm sample" \
  -d "custom_fields[0][dropdown][options][0][value]=balm" \
  -d "custom_fields[0][dropdown][options][1][label]=BB cream sample" \
  -d "custom_fields[0][dropdown][options][1][value]=cream"
```
![ドロップダウンフィールドが設定された決済ページ](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

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

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=invoice" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Invoice number" \
  -d "custom_fields[0][type]=numeric"
```

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

[subscription](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) パラメーターを使用して作成した Checkout セッションのクエリを実行することで、サブスクリプションに関連付けられているカスタムフィールドを取得できます。

```curl
curl -G https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "subscription={{SUBSCRIPTION_ID}}"
```

#### 文字数の検証を追加する

必要に応じて `text` フィールドタイプと `numeric` フィールドタイプの最小文字数と最大文字数の[要件](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length)を指定できます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][minimum_length]=10" \
  -d "custom_fields[0][text][maximum_length]=20" \
  -d "custom_fields[0][optional]=true"
```
![字数制限が設定されたフィールド](https://b.stripecdn.com/docs-statics-srv/assets/between-validation.20431cd8e0c03a028843945d1f1ea314.png)

#### デフォルト値を追加する

必要に応じて、[テキスト](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value)、[数値](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value)、および[ドロップダウン](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value)フィールドタイプのデフォルト値を指定できます。デフォルト値は、支払いページに事前入力されています。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][default_value]=Stella" \
  -d "custom_fields[1][key]=size" \
  -d "custom_fields[1][label][type]=custom" \
  -d "custom_fields[1][label][custom]=Size" \
  -d "custom_fields[1][type]=dropdown" \
  -d "custom_fields[1][dropdown][default_value]=small" \
  -d "custom_fields[1][dropdown][options][0][value]=small" \
  -d "custom_fields[1][dropdown][options][0][label]=Small" \
  -d "custom_fields[1][dropdown][options][1][value]=large" \
  -d "custom_fields[1][dropdown][options][1][label]=Large"
```

## テキストとポリシーをカスタマイズする

顧客が Stripe Checkout を使用して支払う場合は、出荷予定日や処理時間などの追加テキストを表示できます。

> Checkout 上に生成された Stripe のテキスト、Stripe との契約上の義務、Stripe のポリシー、その他適用法に違反する、または誤解を生じさせるカスタムテキストを、この機能を使用して作成することは禁止されています。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```
![配送先住所の収集の近くにあるカスタムテキスト](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

配送先住所の収集フィールドの近くにあるカスタムテキスト
![支払うボタンの上に表示されるカスタムテキスト](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

**支払う**ボタンの上に表示されるカスタムテキスト
![支払うボタンの下に表示されるカスタムテキスト](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

**支払う**ボタンの後に表示されるカスタムテキスト

カスタムテキストは 1200 文字以内で設定できます。ただし、Stripe Checkout はコンバージョンを最適化するため、その他の情報を追加するとコンバージョン率に影響する場合があります。[マークダウン構文](https://www.markdownguide.org/cheat-sheet/)を使用してテキストを太字にしたり、リンクを挿入することができます。

### 送信ボタンをカスタマイズする

Checkout がお客様のビジネスモデルに適合するように、1 回限りの購入に対する Checkout の送信ボタンに表示されるテキストを設定できます。

Session の `submit_type` を定義します。この例 (5 USD の寄付の場合) では、カスタマイズした Checkout 送信ボタンに **$5.00 の寄付** と表示されます。`submit_type` オプションの完全なリストについては、[API リファレンス](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type)を参照してください。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d submit_type=donate \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

## ローカリゼーションとサポート対象言語

Checkout は顧客のブラウザーのロケールをデフォルトで検出し、Stripe がその言語を[サポートしている](https://support.stripe.com/questions/supported-languages-for-stripe-checkout)場合は、翻訳版のページを表示します。Checkout セッションの作成時に `locale` [パラメーター](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale)を渡すことで、Checkout のブラウザーのロケールを上書きできます。

Checkout は、数字と通貨の形式の設定にもロケールを使用します。たとえば、価格が EUR で、ロケールが `auto` に設定された商品を販売する際、英語 (`en`) を使用するように設定されたブラウザーでは €25.00 と表示され、ドイツ語 (`de`) を使用するように設定されたブラウザーでは 25,00 € と表示されます。

### ポリシーと連絡先情報をカスタマイズする

Checkout では、返品、返金、リーガルポリシーおよびサポートの連絡先情報を顧客に表示できます。[Checkout の設定](https://dashboard.stripe.com/settings/checkout)に移動して、以下のような表示情報を設定できます。

- 返品および返金に関するポリシーの詳細
- サポートの電話番号、メールアドレス、および Web サイト
- 利用規約およびプライバシーポリシーへのリンク

この情報を提示することで、買い手の信頼を高め、カート離脱率を最小化できます。

### サポートおよびリーガルポリシーの設定

[Checkout の設定](https://dashboard.stripe.com/settings/checkout)で、**連絡先情報**を有効にして、サポートの連絡先情報をセッションに追加します。同様に、**リーガルポリシー**を選択して、**利用規約**と**プライバシーポリシー**へのリンクをセッションに追加します。顧客が決済フローを完了する際に、リーガルポリシーに黙示的に同意するように求める場合は、**規約への同意を表示**というチェックボックスを選択します。

[公開情報の設定](https://dashboard.stripe.com/settings/public)で、サポートの連絡先情報とリーガルポリシーへのリンクを追加する必要があります。

以下のプレビューは、サポートの連絡先情報、ストアのリーガルポリシーへのリンク、および支払い条件に関する情報が記載されたダイアログが、Checkout の画面にどのように表示されるかを示しています。
![連絡先情報が記載された決済ページです。](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Checkout の連絡先情報のプレビュー
![リーガルポリシーが記載された決済ページです。](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Checkout のリーガルポリシーのプレビュー

### 返品および返金に関するポリシーの設定

**返品および返金に関するポリシー**を有効にして、返品、返金、または交換に関するポリシーを表示します。物品を販売するビジネスは、返品に関するポリシーを使用しますが、デジタル商品またはカスタマイズされた物品を販売するビジネスは通常、返金に関するポリシーを使用します。これらは併記可能であるため、ビジネスが双方のカテゴリの商品を販売している場合は、両方のオプションを選択できます。以下のような返品と返金の詳細を編集できます。

- 返品、返金、交換を受け入れるかどうか
- 返品、返金、交換が無償であるか、または手数料が課せられるか
- 返品、返金、交換を受け入れるのは、購入後何日間か
- 顧客が配送されたアイテムを返品する方法
- 実店舗での返品は可能かどうか
- 返品および返金に関するポリシー全文へのリンク
- カスタムメッセージ

無料の返品、返金、交換を受け入れている場合、Checkout はこのポリシーを顧客に強調表示します。

以下のプレビューは、返品に関するポリシーが Checkout でどのように表示されるかを示しています。この例では、60 日以内の返送または実店舗での全額返金 (または交換) に対応している購入に関するものです。返金に対しても同様の情報を表示できます。
![Checkout の返品に関するポリシーのプレビュー](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Checkout の返品に関するポリシーのプレビュー
![Checkout のポリシーハイライトのプレビュー](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Checkout のポリシーハイライトのプレビュー。

#### 利用規約への同意を得る

ビジネスでは、顧客が支払いを行う前に利用規約への同意を求めることがよくあります。これは、商品またはサブスクリプションのタイプによって異なります。Checkout では、支払いの前に顧客に利用規約への同意を求めて必要な契約書を収集することができます。
![利用規約への同意を得る](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

利用規約への同意を得る

セッションを作成する際に、Stripe Checkout で利用規約への同意を得ることができます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=2" \
  -d mode=payment \
  -d "consent_collection[terms_of_service]=required" \
  --data-urlencode "custom_text[terms_of_service_acceptance][message]=I agree to the [Terms of Service](https://example.com/terms)" \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

`consent_collection.terms_of_service='required'` の場合、Checkout に利用規約への同意を収集するためのチェックボックスが動的に表示されます。`consent_collection.terms_of_service='none'` の場合、Checkout にチェックボックスは表示されず、また顧客に利用規約への同意が求められることもありません。利用規約への同意を求める前に、ビジネスの[公開情報](https://dashboard.stripe.com/settings/public)に利用規約の URL を設定してください。プライバシーポリシーの URL の設定は任意です。[公開情報](https://dashboard.stripe.com/settings/public)でプライバシーポリシーの URL が設定されている場合、Checkout にもプライバシーポリシーへのリンクが表示されます。

顧客が決済フローを完了した後、`checkout.session.completed` Webhook の Session オブジェクトを確認するか、API を使用して Session を取得することで、顧客が利用規約に同意したことを確認できます。利用規約が承認されると、Session の [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) フィールドは `accepted` に設定されます。

`custom_text.terms_of_service_acceptance` を使用して、チェックボックスの横に表示されるテキストをカスタマイズできます。`consent_collection.terms_of_service='required'` を設定する必要があります。独自の用語を使用する際は、マークダウンリンクを挿入します。例: `I agree to the [Terms of Service](https://example.com/terms)`

> このテキストに変更を加える前に、弁護士およびコンプラインスアドバイザーと相談することをお勧めします。Checkout 上に生成された Stripe のテキスト、Stripe との契約上の義務、Stripe のポリシー、その他適用法に違反する、または誤解を生じさせるカスタムテキストは、この機能を使用して表示することはできません。

#### プロモーションメールへの同意を収集する

プロモーションメールを送信して、顧客に新製品について知らせたり、クーポンや割引を案内したりできます。これを行う前に、プロモーションメールを受信するための[同意を得る](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md)必要があります。

## 決済手段の再利用規約とサブスクリプション規約をカスタマイズする

セッションが `setup` または `subscription` モードの場合、あるいは `setup_future_usage` が設定された `payment` モードの場合、Checkout は顧客の決済手段の再利用に関するメッセージを表示します。メッセージには、選択された決済手段に固有の情報を含めることができます。デフォルトのテキストは非表示にしたりカスタマイズしたりできますが、決済手段固有のテキストはできません。

サブスクリプションの場合、カスタムテキストには次の情報を含めることができます。

- サブスクリプション規約へのリンク
- カスタマーポータルへのリンク
- キャンセルの手順とポリシー
![サブスクリプションモードにおけるデフォルトの決済手段の再利用規約の表示](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

サブスクリプションモードにおけるデフォルトの決済手段の再利用規約

> このテキストをカスタマイズすることで、お客様には規制遵守の責任が生じます。たとえば、カードネットワークのルールや地域の規制に変更が生じた場合、適宜テキストを更新しなければなりません。この機能を使用する場合は必ず、会社の法務チームに相談するか、決済手段の再利用に関する情報を含むカスタムテキストを設定してください。カスタマイズしたテキストが、サポート予定のすべてのモードに対応していることを確認してください。

決済手段の再利用規約のテキストを非表示にするには、`consent_collection.payment_method_reuse_agreement.position='hidden'` を設定します。Checkout では、決済手段の再利用について記述するデフォルトのテキストは表示されなくなります。Stripe のデフォルトテキストの代わりに自分でテキストを設定するには、`custom_text.after_submit.message` を設定します。`custom_text.submit` または `custom_text.terms_of_service_acceptance` を使用して、自分で設定したテキストを表示することもできます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "consent_collection[payment_method_reuse_agreement][position]=hidden" \
  --data-urlencode "custom_text[after_submit][message]=You can cancel your subscription at any time by [logging into your account](https://www.example.com/)"
```


# Checkout エレメント

> This is a Checkout エレメント for when platform is web and payment-ui is elements. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=elements.

Checkout エレメントを使用する場合、Custom コンポーネントは必要ありません。独自のインタフェースで Elements を構成し、必要に応じて間に独自の Custom コンポーネントを挿入できます。