# 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.

> Você não tem permissão para usar esse recurso para criar um texto personalizado que viole ou crie ambiguidades com o texto gerado pela Stripe no Checkout, com as obrigações sob seu contrato da Stripe, as políticas da Stripe e as leis aplicáveis.

```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"
```
![Texto personalizado próximo à coleta do endereço de entrega](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Texto personalizado próximo aos campos de coleta do endereço de entrega
![Texto personalizado acima do botão de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texto personalizado acima do botão **Pagar**
![Texto personalizado abaixo do botão de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Texto personalizado após o botão **Pagar**

Seu texto personalizado pode ter até 1.200 caracteres. No entanto, o Stripe Checkout é otimizado para conversão e acrescentar informações adicionais pode afetar sua taxa de conversão. Você pode colocar texto em negrito ou inserir um link usando a [sintaxe de markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Para alinhar melhor o Checkout com o modelo de negócio, configure o texto exibido no botão de envio do Checkout para compras únicas.

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

## Idiomas aceitos e versões traduzidas

Por padrão, o Checkout detecta a localidade do navegador do cliente e exibe uma versão traduzida da página no idioma escolhido, se a Stripe [aceitá-la](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Você substituir a localidade do navegador para o Checkout passando o [parâmetro](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` durante a criação de uma sessão do Checkout.

O Checkout também usa a localidade para formatar números e moedas. Por exemplo, na venda de um produto com preço em euros com a localidade definida como `auto`, um navegador configurado para usar inglês (`en`) mostra “€25.00” e outro configurado para usar alemão (`de`) mostra “25,00 €”.

### Customize policies and contact information 

Você pode mostrar os dados de contato e as políticas de devolução, reembolso e jurídicas aos clientes no Checkout. Acesse [Configurações do Checkout](https://dashboard.stripe.com/settings/checkout) para definir as informações a serem exibidas, como:

- Detalhes das políticas de devolução e reembolso
- O número de telefone, e-mail e site do seu suporte
- Links para os seus termos de serviço e a sua política de privacidade

A apresentação dessas informações pode aumentar a confiança dos compradores e reduzir o abandono de carrinhos.

### Configurar políticas jurídicas e de suporte

Para adicionar dados de contato às sessões em [Configurações do Checkout](https://dashboard.stripe.com/settings/checkout), habilite **Dados de contato**. Da mesma forma, habilite **Políticas jurídicas** para adicionar links dos **Termos de serviço** e da **Política de privacidade** às sessões. Se você precisa que os clientes aceitem implicitamente suas políticas jurídicas quando concluírem o checkout, marque a caixa de seleção **Exibir concordância com os termos jurídicos**.

Você precisa adicionar links para os dados de contato e as políticas jurídicas nas [Configurações de dados públicos](https://dashboard.stripe.com/settings/public).

As visualizações a seguir mostram como o Checkout exibe um diálogo com dados de contato de suporte, links para as políticas jurídicas da loja e informações sobre os termos de pagamento.
![Uma página de checkout com dados de contato.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Visualização de dados de contato no Checkout.
![Uma página de checkout com políticas jurídicas.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Visualização de políticas jurídicas no Checkout.

### Configurar políticas de devolução e reembolso

Para exibir suas políticas de devolução, reembolso ou troca, habilite **Políticas de devolução e reembolso**. Embora as empresas que vendem mercadorias físicas usem políticas de devolução, as que vendem mercadorias físicas personalizadas ou digitais costumam adotar políticas de reembolso. Como não são mutuamente exclusivas, você pode selecionar as duas opções quando sua empresa vende as duas categorias de mercadorias. Os detalhes de devolução e reembolso podem ser editados para especificar:

- Se você aceita devoluções, reembolsos ou trocas
- Se devoluções, reembolsos ou trocas são gratuitos ou estão sujeitos a uma tarifa
- Quantos dias após a compra você aceita devoluções, reembolsos ou trocas
- Como os clientes podem devolver itens recebidos
- Se você aceita devoluções nas lojas físicas
- Um link para a política completa de devolução e reembolso
- Uma mensagem personalizada

Se você aceita devoluções, reembolsos ou trocas gratuitas, o Checkout destaca a política para os clientes.

As visualizações a seguir mostram como o Checkout exibe uma política de devolução. Neste exemplo, os produtos podem ser devolvidos por remessa ou nas lojas físicas até 60 dias após a compra para obter um reembolso completo (ou troca). Informações semelhantes podem ser exibidas para reembolsos.
![Visualização de políticas de devolução no Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Visualização das políticas de devolução no Checkout.
![Visualização de um destaque de política no Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Visualização de um destaque de política no Checkout.

#### Colete um contrato de termos de serviço

Muitas vezes, as empresas exigem que os clientes concordem com os termos de serviço antes de pagar. Isso pode depender do tipo de produto ou assinatura. O Checkout ajuda a obter a concordância necessária exigindo que seus termos sejam aceitos pelo cliente antes de pagar.
![Coletar contrato de termos de serviço](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Coletar contrato de termos de serviço

Você pode coletar um contrato de termos de serviço com o Stripe Checkout ao criar uma sessão:

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

Quando `consent_collection.terms_of_service='required'`, o Checkout exibe dinamicamente uma caixa de seleção para coletar o contrato de termos de serviço do cliente. Se `consent_collection.terms_of_service='none'`, o Checkout não exibirá a caixa de seleção e não exigirá que os clientes aceitem os termos de serviço. Antes de exigir a concordância com seus termos, defina o URL dos termos de serviço nos [dados públicos](https://dashboard.stripe.com/settings/public) da sua empresa. A definição de um URL de política de privacidade é opcional. O Checkout também direciona para sua política de privacidade quando um URL para essa política é definido em seus [dados públicos](https://dashboard.stripe.com/settings/public).

Após um cliente concluir o checkout, você pode verificar se ele aceitou seus termos de serviço observando o objeto Sessão no webhook `checkout.session.completed` ou recuperando a Sessão usando a API. Quando os termos são aceitos, o campo [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) da sessão é definido como `accepted`.

Você pode personalizar o texto que aparece ao lado da caixa de seleção usando `custom_text.terms_of_service_acceptance`. Você precisa definir `consent_collection.terms_of_service='required'`. Para usar seus próprios termos, insira um link de markdown. Por exemplo: `I agree to the [Terms of Service](https://example.com/terms)`

> Consulte seus assessores jurídicos e de conformidade antes de fazer qualquer alteração neste texto. Você não pode usar este recurso para exibir texto personalizado que viole ou crie ambiguidades com o texto gerado pela Stripe no Checkout, as obrigações decorrentes do seu contrato da Stripe, as políticas da Stripe e as leis aplicáveis.

#### Collect consent for promotional emails

Você pode enviar e-mails promocionais para informar os clientes sobre novos produtos e para compartilhar cupons e descontos. Antes de fazer isso, você precisa [coletar o consentimento deles](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) para receber e-mails promocionais.

## Personalize o contrato de reutilização de formas de pagamento e os termos de assinatura

Quando uma sessão está no modo `setup` ou `subscription`, ou no modo `payment` com `setup_future_usage` definido, o Checkout exibe uma mensagem sobre a reutilização da forma de pagamento do cliente. A mensagem pode incluir dados específicos da forma de pagamento selecionada. Você pode ocultar ou personalizar o texto padrão, mas não o texto específico da forma de pagamento.

Para uma assinatura, o texto personalizado pode incluir informações como as seguintes:

- Um link para seus termos de assinatura
- Um link para o portal do cliente
- Mecanismos e políticas de cancelamento
![Exibição do contrato de reutilização da forma de pagamento padrão no modo de assinatura](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Forma de pagamento padrão Reutilizar contrato no modo de assinatura

> Ao personalizar este texto, você será responsável por manter a conformidade, o que inclui atualizá-lo à medida que as regras das bandeiras de cartão e os regulamentos locais mudam. Não use esse recurso sem consultar sua equipe jurídica ou definir um texto personalizado com informações sobre a reutilização da forma de pagamento. Certifique-se de que seu texto personalizado cubra todos os modos que você planeja aceitar.

Para ocultar o texto do contrato de reutilização da forma de pagamento, defina `consent_collection.payment_method_reuse_agreement.position='hidden'`. O Checkout não exibirá a linguagem padrão que controla a reutilização da forma de pagamento. Para definir seu próprio texto no lugar do idioma padrão da Stripe, defina `custom_text.after_submit.message`. Você também pode usar `custom_text.submit` ou `custom_text.terms_of_service_acceptance` para exibir sua própria versão desse idioma.

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

> Você não tem permissão para usar esse recurso para criar um texto personalizado que viole ou crie ambiguidades com o texto gerado pela Stripe no Checkout, com as obrigações sob seu contrato da Stripe, as políticas da Stripe e as leis aplicáveis.

```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"
```
![Texto personalizado próximo à coleta do endereço de entrega](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Texto personalizado próximo aos campos de coleta do endereço de entrega
![Texto personalizado acima do botão de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texto personalizado acima do botão **Pagar**
![Texto personalizado abaixo do botão de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Texto personalizado após o botão **Pagar**

Seu texto personalizado pode ter até 1.200 caracteres. No entanto, o Stripe Checkout é otimizado para conversão e acrescentar informações adicionais pode afetar sua taxa de conversão. Você pode colocar texto em negrito ou inserir um link usando a [sintaxe de markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Para alinhar melhor o Checkout com o modelo de negócio, configure o texto exibido no botão de envio do Checkout para compras únicas.

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

## Idiomas aceitos e versões traduzidas

Por padrão, o Checkout detecta a localidade do navegador do cliente e exibe uma versão traduzida da página no idioma escolhido, se a Stripe [aceitá-la](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Você substituir a localidade do navegador para o Checkout passando o [parâmetro](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` durante a criação de uma sessão do Checkout.

O Checkout também usa a localidade para formatar números e moedas. Por exemplo, na venda de um produto com preço em euros com a localidade definida como `auto`, um navegador configurado para usar inglês (`en`) mostra “€25.00” e outro configurado para usar alemão (`de`) mostra “25,00 €”.

### Customize policies and contact information 

Você pode mostrar os dados de contato e as políticas de devolução, reembolso e jurídicas aos clientes no Checkout. Acesse [Configurações do Checkout](https://dashboard.stripe.com/settings/checkout) para definir as informações a serem exibidas, como:

- Detalhes das políticas de devolução e reembolso
- O número de telefone, e-mail e site do seu suporte
- Links para os seus termos de serviço e a sua política de privacidade

A apresentação dessas informações pode aumentar a confiança dos compradores e reduzir o abandono de carrinhos.

### Configurar políticas jurídicas e de suporte

Para adicionar dados de contato às sessões em [Configurações do Checkout](https://dashboard.stripe.com/settings/checkout), habilite **Dados de contato**. Da mesma forma, habilite **Políticas jurídicas** para adicionar links dos **Termos de serviço** e da **Política de privacidade** às sessões. Se você precisa que os clientes aceitem implicitamente suas políticas jurídicas quando concluírem o checkout, marque a caixa de seleção **Exibir concordância com os termos jurídicos**.

Você precisa adicionar links para os dados de contato e as políticas jurídicas nas [Configurações de dados públicos](https://dashboard.stripe.com/settings/public).

As visualizações a seguir mostram como o Checkout exibe um diálogo com dados de contato de suporte, links para as políticas jurídicas da loja e informações sobre os termos de pagamento.
![Uma página de checkout com dados de contato.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Visualização de dados de contato no Checkout.
![Uma página de checkout com políticas jurídicas.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Visualização de políticas jurídicas no Checkout.

### Configurar políticas de devolução e reembolso

Para exibir suas políticas de devolução, reembolso ou troca, habilite **Políticas de devolução e reembolso**. Embora as empresas que vendem mercadorias físicas usem políticas de devolução, as que vendem mercadorias físicas personalizadas ou digitais costumam adotar políticas de reembolso. Como não são mutuamente exclusivas, você pode selecionar as duas opções quando sua empresa vende as duas categorias de mercadorias. Os detalhes de devolução e reembolso podem ser editados para especificar:

- Se você aceita devoluções, reembolsos ou trocas
- Se devoluções, reembolsos ou trocas são gratuitos ou estão sujeitos a uma tarifa
- Quantos dias após a compra você aceita devoluções, reembolsos ou trocas
- Como os clientes podem devolver itens recebidos
- Se você aceita devoluções nas lojas físicas
- Um link para a política completa de devolução e reembolso
- Uma mensagem personalizada

Se você aceita devoluções, reembolsos ou trocas gratuitas, o Checkout destaca a política para os clientes.

As visualizações a seguir mostram como o Checkout exibe uma política de devolução. Neste exemplo, os produtos podem ser devolvidos por remessa ou nas lojas físicas até 60 dias após a compra para obter um reembolso completo (ou troca). Informações semelhantes podem ser exibidas para reembolsos.
![Visualização de políticas de devolução no Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Visualização das políticas de devolução no Checkout.
![Visualização de um destaque de política no Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Visualização de um destaque de política no Checkout.

#### Colete um contrato de termos de serviço

Muitas vezes, as empresas exigem que os clientes concordem com os termos de serviço antes de pagar. Isso pode depender do tipo de produto ou assinatura. O Checkout ajuda a obter a concordância necessária exigindo que seus termos sejam aceitos pelo cliente antes de pagar.
![Coletar contrato de termos de serviço](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Coletar contrato de termos de serviço

Você pode coletar um contrato de termos de serviço com o Stripe Checkout ao criar uma sessão:

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

Quando `consent_collection.terms_of_service='required'`, o Checkout exibe dinamicamente uma caixa de seleção para coletar o contrato de termos de serviço do cliente. Se `consent_collection.terms_of_service='none'`, o Checkout não exibirá a caixa de seleção e não exigirá que os clientes aceitem os termos de serviço. Antes de exigir a concordância com seus termos, defina o URL dos termos de serviço nos [dados públicos](https://dashboard.stripe.com/settings/public) da sua empresa. A definição de um URL de política de privacidade é opcional. O Checkout também direciona para sua política de privacidade quando um URL para essa política é definido em seus [dados públicos](https://dashboard.stripe.com/settings/public).

Após um cliente concluir o checkout, você pode verificar se ele aceitou seus termos de serviço observando o objeto Sessão no webhook `checkout.session.completed` ou recuperando a Sessão usando a API. Quando os termos são aceitos, o campo [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) da sessão é definido como `accepted`.

Você pode personalizar o texto que aparece ao lado da caixa de seleção usando `custom_text.terms_of_service_acceptance`. Você precisa definir `consent_collection.terms_of_service='required'`. Para usar seus próprios termos, insira um link de markdown. Por exemplo: `I agree to the [Terms of Service](https://example.com/terms)`

> Consulte seus assessores jurídicos e de conformidade antes de fazer qualquer alteração neste texto. Você não pode usar este recurso para exibir texto personalizado que viole ou crie ambiguidades com o texto gerado pela Stripe no Checkout, as obrigações decorrentes do seu contrato da Stripe, as políticas da Stripe e as leis aplicáveis.

#### Collect consent for promotional emails

Você pode enviar e-mails promocionais para informar os clientes sobre novos produtos e para compartilhar cupons e descontos. Antes de fazer isso, você precisa [coletar o consentimento deles](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) para receber e-mails promocionais.

## Personalize o contrato de reutilização de formas de pagamento e os termos de assinatura

Quando uma sessão está no modo `setup` ou `subscription`, ou no modo `payment` com `setup_future_usage` definido, o Checkout exibe uma mensagem sobre a reutilização da forma de pagamento do cliente. A mensagem pode incluir dados específicos da forma de pagamento selecionada. Você pode ocultar ou personalizar o texto padrão, mas não o texto específico da forma de pagamento.

Para uma assinatura, o texto personalizado pode incluir informações como as seguintes:

- Um link para seus termos de assinatura
- Um link para o portal do cliente
- Mecanismos e políticas de cancelamento
![Exibição do contrato de reutilização da forma de pagamento padrão no modo de assinatura](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Forma de pagamento padrão Reutilizar contrato no modo de assinatura

> Ao personalizar este texto, você será responsável por manter a conformidade, o que inclui atualizá-lo à medida que as regras das bandeiras de cartão e os regulamentos locais mudam. Não use esse recurso sem consultar sua equipe jurídica ou definir um texto personalizado com informações sobre a reutilização da forma de pagamento. Certifique-se de que seu texto personalizado cubra todos os modos que você planeja aceitar.

Para ocultar o texto do contrato de reutilização da forma de pagamento, defina `consent_collection.payment_method_reuse_agreement.position='hidden'`. O Checkout não exibirá a linguagem padrão que controla a reutilização da forma de pagamento. Para definir seu próprio texto no lugar do idioma padrão da Stripe, defina `custom_text.after_submit.message`. Você também pode usar `custom_text.submit` ou `custom_text.terms_of_service_acceptance` para exibir sua própria versão desse idioma.

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