# Extend checkout with custom components

Display custom text and collect additional information on Checkout Sessions.

# Hosted page

> This is a Hosted page 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.

## Add custom fields 

You can add custom fields on the payment form to collect additional information from your customers. The information is available after the payment is complete and is useful for fulfilling the purchase.

Custom fields have the following limitations:

- Up to three fields allowed.
- Not available in `setup` mode.
- Support for up to 255 characters on text fields.
- Support for up to 255 digits on numeric fields.
- Support for up to 200 options on dropdown fields.

> Don’t use custom fields to collect personal, protected, or sensitive data, or information restricted by law.

### Create a Checkout Session 

Create a Checkout Session while specifying an array of [custom fields](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields). Each field must have a unique `key` that your integration uses to reconcile the field. Also provide a label for the field that you display to your customer. Labels for custom fields aren’t translated, but you can use the [locale](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) parameter to set the language of your Checkout Session to match the same language as your labels.

```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)
### Retrieve custom fields 

When your customer completes the Checkout Session, we send a [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) with the completed fields.

Example `checkout.session.completed` payload:

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

You can also look up and edit custom field values from the Dashboard, by clicking into a specific payment in the [Transactions](https://dashboard.stripe.com/payments) tab or including custom field values when exporting your payments from the [Dashboard](https://dashboard.stripe.com/payments).

### Use a custom field 

#### Mark a field as optional 

By default, customers must complete all fields before completing payment. To mark a field as optional, pass in `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)

#### Add a dropdown field 

A dropdown field presents your customers with a list of options to select from. To create a dropdown field, specify `type=dropdown` and a list of options, each with a `label` and a `value`. The `label` displays to the customer while your integration uses the `value` to reconcile which option the customer selected.

```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"
```
![A checkout page with a dropdown field](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

#### Add a numbers only field 

A numbers-only field provides your customers a text field that only accepts numerical values, up to 255 digits. To create a numbers-only field, specify `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"
```

#### Retrieve custom fields for a subscription 

You can retrieve the custom fields associated with a subscription by querying for the Checkout Session that created it using the [subscription](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) parameter.

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

#### Add character length validations 

You can optionally specify a minimum and maximum character length [requirement](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length) for `text` and `numeric` field types.

```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"
```
![A field with character limits](https://b.stripecdn.com/docs-statics-srv/assets/between-validation.20431cd8e0c03a028843945d1f1ea314.png)

#### Add default values 

You can optionally provide a default value for the [text](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value), [numeric](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value), and [dropdown](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value) field types. Default values are prefilled on the payment page.

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

## Customize text and policies 

When customers pay with Stripe Checkout, you can present additional text, such as shipping and processing times.

> 您不被允许使用此功能创建会违反或与以下内容产生歧义的自定义文本：Stripe 在 Checkout 页面生成的文本、您与 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 针对转化进行了优化，添加额外信息可能会影响您的转化率。您可以加粗文本或用 [Markdown 语法](https://www.markdownguide.org/cheat-sheet/)插入链接。

### Customize the Submit button 

为了使 Checkout 功能更符合您的业务模式，请为一次性购买操作中的 Checkout 提交按钮配置所显示的文本。

Define a `submit_type` on your session. In this example (for a 5 USD donation), your customized Checkout submit button displays **Donate \5.00 USD**. See the [API reference](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type) for a complete list of `submit_type` options.

```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 Session 时，可以通过传递 `locale` [parameter](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) 来覆盖 Checkout 的浏览器区域设置。

Checkout 还会用位置来确定数字和货币的格式。例如，销售一种产品，位置设置为 `auto`，价格的币种设置为 EUR，那么配置为使用英语 English (`en`) 的浏览器会显示 €25.00，而配置为德语 German (`de`) 的浏览器，则显示 25,00 €。

### Customize policies and contact information 

您可以在 Checkout 上向客户显示您的退货、退款、法律政策及客服联系信息。前往 [Checkout 设置](https://dashboard.stripe.com/settings/checkout)，配置想要显示的信息：

- 您的退货和退款政策详情
- 您的客服电话、邮箱和网站
- 您的服务条款和隐私政策链接

展示该信息有利于增强买家信心，最小化购物车放弃率。

### 配置支持和法律政策

在 [Checkout 设置](https://dashboard.stripe.com/settings/checkout)中，启用**联系信息**，向您的会话中添加客户支持的联系信息。与之类似，通过选择**法律政策**，向您的会话添加**服务条款**和**隐私政策**的链接。如果您要求客户在完成结账时隐式地同意您的法律政策，则选择复选框**显示法律条款协议**。

您必须在您的[公开详情设置](https://dashboard.stripe.com/settings/public)中添加您的客户支持的联系信息和法律政策链接。

下面的预览图显示了 Checktout 如何通过对话框的形式显示客服联系信息、店铺法律政策的链接以及相关付款条款的信息。
![包含联系信息的结账页面。](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)

收集服务协议条款

您可以在创建 Session 时通过 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.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'`。要使用您自己的条款，请插入一个 Markdown 链接。例如：`I agree to the [Terms of Service](https://example.com/terms)`

> 在对此文本进行任何更改之前，请咨询您的法律和合规顾问。您不得使用此功能显示违反 Stripe 协议下的义务、Stripe 政策和适用法律的文本，或导致结账时 Stripe 生成的文本模糊的自定义文本。

#### Collect consent for promotional emails

您可以发送促销邮件来通知客户新产品并分享优惠券和折扣。在执行此操作前，必须先[收集他们的许可](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/)"
```


# Embedded page

> This is a Embedded page 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.

You can add custom fields on the payment form to collect additional information from your customers. You can also customize the text that your customers see, and the policies Checkout displays.

## Add custom fields 

You can add custom fields on the payment form to collect additional information from your customers. The information is available after the payment is complete and is useful for fulfilling the purchase.

Custom fields have the following limitations:

- Up to three fields allowed.
- Not available in `setup` mode.
- Support for up to 255 characters on text fields.
- Support for up to 255 digits on numeric fields.
- Support for up to 200 options on dropdown fields.

> Don’t use custom fields to collect personal, protected, or sensitive data, or information restricted by law.

### Create a Checkout Session 

Create a Checkout Session while specifying an array of [custom fields](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields). Each field must have a unique `key` that your integration uses to reconcile the field. Also provide a label for the field that you display to your customer. Labels for custom fields aren’t translated, but you can use the [locale](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) parameter to set the language of your Checkout Session to match the same language as your labels.

```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)
### Retrieve custom fields 

When your customer completes the Checkout Session, we send a [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) with the completed fields.

Example `checkout.session.completed` payload:

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

You can also look up and edit custom field values from the Dashboard, by clicking into a specific payment in the [Transactions](https://dashboard.stripe.com/payments) tab or including custom field values when exporting your payments from the [Dashboard](https://dashboard.stripe.com/payments).

### Use a custom field 

#### Mark a field as optional 

By default, customers must complete all fields before completing payment. To mark a field as optional, pass in `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)

#### Add a dropdown field 

A dropdown field presents your customers with a list of options to select from. To create a dropdown field, specify `type=dropdown` and a list of options, each with a `label` and a `value`. The `label` displays to the customer while your integration uses the `value` to reconcile which option the customer selected.

```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"
```
![A checkout page with a dropdown field](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

#### Add a numbers only field 

A numbers-only field provides your customers a text field that only accepts numerical values, up to 255 digits. To create a numbers-only field, specify `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"
```

#### Retrieve custom fields for a subscription 

You can retrieve the custom fields associated with a subscription by querying for the Checkout Session that created it using the [subscription](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) parameter.

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

#### Add character length validations 

You can optionally specify a minimum and maximum character length [requirement](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length) for `text` and `numeric` field types.

```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"
```
![A field with character limits](https://b.stripecdn.com/docs-statics-srv/assets/between-validation.20431cd8e0c03a028843945d1f1ea314.png)

#### Add default values 

You can optionally provide a default value for the [text](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value), [numeric](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value), and [dropdown](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value) field types. Default values are prefilled on the payment page.

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

## Customize text and policies 

When customers pay with Stripe Checkout, you can present additional text, such as shipping and processing times.

> 您不被允许使用此功能创建会违反或与以下内容产生歧义的自定义文本：Stripe 在 Checkout 页面生成的文本、您与 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 针对转化进行了优化，添加额外信息可能会影响您的转化率。您可以加粗文本或用 [Markdown 语法](https://www.markdownguide.org/cheat-sheet/)插入链接。

### Customize the Submit button 

为了使 Checkout 功能更符合您的业务模式，请为一次性购买操作中的 Checkout 提交按钮配置所显示的文本。

Define a `submit_type` on your session. In this example (for a 5 USD donation), your customized Checkout submit button displays **Donate \5.00 USD**. See the [API reference](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type) for a complete list of `submit_type` options.

```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 Session 时，可以通过传递 `locale` [parameter](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) 来覆盖 Checkout 的浏览器区域设置。

Checkout 还会用位置来确定数字和货币的格式。例如，销售一种产品，位置设置为 `auto`，价格的币种设置为 EUR，那么配置为使用英语 English (`en`) 的浏览器会显示 €25.00，而配置为德语 German (`de`) 的浏览器，则显示 25,00 €。

### Customize policies and contact information 

您可以在 Checkout 上向客户显示您的退货、退款、法律政策及客服联系信息。前往 [Checkout 设置](https://dashboard.stripe.com/settings/checkout)，配置想要显示的信息：

- 您的退货和退款政策详情
- 您的客服电话、邮箱和网站
- 您的服务条款和隐私政策链接

展示该信息有利于增强买家信心，最小化购物车放弃率。

### 配置支持和法律政策

在 [Checkout 设置](https://dashboard.stripe.com/settings/checkout)中，启用**联系信息**，向您的会话中添加客户支持的联系信息。与之类似，通过选择**法律政策**，向您的会话添加**服务条款**和**隐私政策**的链接。如果您要求客户在完成结账时隐式地同意您的法律政策，则选择复选框**显示法律条款协议**。

您必须在您的[公开详情设置](https://dashboard.stripe.com/settings/public)中添加您的客户支持的联系信息和法律政策链接。

下面的预览图显示了 Checktout 如何通过对话框的形式显示客服联系信息、店铺法律政策的链接以及相关付款条款的信息。
![包含联系信息的结账页面。](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)

收集服务协议条款

您可以在创建 Session 时通过 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.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'`。要使用您自己的条款，请插入一个 Markdown 链接。例如：`I agree to the [Terms of Service](https://example.com/terms)`

> 在对此文本进行任何更改之前，请咨询您的法律和合规顾问。您不得使用此功能显示违反 Stripe 协议下的义务、Stripe 政策和适用法律的文本，或导致结账时 Stripe 生成的文本模糊的自定义文本。

#### Collect consent for promotional emails

您可以发送促销邮件来通知客户新产品并分享优惠券和折扣。在执行此操作前，必须先[收集他们的许可](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 elements

> This is a Checkout elements 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.

Custom components aren’t necessary when using Checkout elements. You can compose the elements in your own interface and insert your own custom components in between them as needed.