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

> Il vous est interdit d’utiliser cette fonctionnalité pour créer un texte personnalisé qui entre en conflit ou crée une ambiguïté avec le texte généré par Stripe dans Checkout ou les obligations en vertu de votre contrat Stripe, les politiques de Stripe et les lois applicables.

```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"
```
![Texte personnalisé près de la collecte de l'adresse de livraison](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Texte personnalisé près des champs de collecte de l’adresse de livraison
![Texte personnalisé au-dessus du bouton Payer](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texte personnalisé au-dessus du bouton **Payer**
![Texte personnalisé sous le bouton Payer](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Texte personnalisé après le bouton **Payer**

Votre texte personnalisé peut comporter jusqu’à 1&nbsp;200&nbsp;caractères. Cependant, Stripe Checkout est optimisé pour la conversion et l’ajout d’informations supplémentaires peut affecter votre taux de conversion. Vous pouvez utilisez des caractères gras ou insérer un lien en utilisant la [syntaxe Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Pour mieux aligner Checkout sur votre modèle économique, configurez le texte affiché sur le bouton d’envoi Checkout pour les achats ponctuels.

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

## Localisation et langues prises en charge

Par défaut, Checkout détectera les paramètres régionaux du navigateur du client et affichera une version traduite de la page dans sa langue, si Stripe [la prend en charge](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Vous pouvez remplacer les paramètres régionaux du navigateur pour Checkout en transmettant le [paramètre](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` lorsque vous créez une session Checkout.

Checkout utilise également les paramètres régionaux pour formater les chiffres et les devises. Par exemple, lors de la vente d’un produit dont le prix est défini en EUR avec les paramètres régionaux définis sur `auto`, un navigateur configuré pour utiliser l’anglais (`en`) affichera €25.00, tandis qu’une configuration pour l’allemand (`de`) affichera 25,00&nbsp;€.

### Customize policies and contact information 

Vous pouvez afficher votre politique de retour et de remboursement, vos politiques juridiques, ainsi que les coordonnées de votre service d’assistance pour vos clients dans Checkout. Accédez aux [paramètres Checkout](https://dashboard.stripe.com/settings/checkout) pour configurer les informations que vous souhaitez afficher, y compris les éléments suivants&nbsp;:

- Détails concernant vos politiques de retour et de remboursement
- Site Web, adresse courriel et numéro de téléphone de votre service d’assistance
- Liens vers vos Conditions d’utilisation du service et votre Politique de confidentialité

Présentées clairement, ces informations peuvent mettre vos clients en confiance et réduire le taux d’abandon des paniers.

### Configurer le service d’assistance et les politiques juridiques

Dans les [paramètres Checkout](https://dashboard.stripe.com/settings/checkout), activez l’option **Coordonnées** pour ajouter les coordonnées du service d’assistance à vos sessions. De la même manière, ajoutez les liens vers vos **Conditions d’utilisation du service** et votre **Politique de confidentialité** après avoir activé l’option **Politiques juridiques**. Si vous demandez à vos clients de consentir implicitement à vos politiques juridiques lorsqu’ils effectuent leur paiement, cochez la case **Afficher le consentement aux conditions juridiques**.

Vous devez ajouter les liens vers les coordonnées de votre service d’assistance et vers vos politiques juridiques dans vos [paramètres d’informations publiques sur l’entreprise](https://dashboard.stripe.com/settings/public).

Les aperçus suivants montrent comment Checkout affiche une boîte de dialogue avec les coordonnées du service d’assistance, les liens vers les politiques juridiques, ainsi que les informations concernant les conditions de paiement.
![Une page de paiement avec des coordonnées.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Aperçu des coordonnées dans Checkout.
![Une page de paiement avec des politiques juridiques.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Aperçu des politiques juridiques dans Checkout.

### Configurez les politiques de retour et de remboursement

Activez l’option **Politiques de retour et de remboursement** pour afficher vos politiques de retour, de remboursement ou d’échange. Si les entreprises qui vendent des biens physiques utilisent des politiques de retour, celles qui vendent des biens numériques ou des biens physiques personnalisés utilisent généralement des politiques de remboursement. Comme elles ne s’excluent pas mutuellement, vous pouvez sélectionner les deux options si votre entreprise vend ces deux catégories de biens. Vous pouvez modifier les détails de vos retours et remboursements, en précisant notamment&nbsp;:

- Si vous acceptez les retours, les remboursements ou les échanges
- Si les retours, les remboursements ou les échanges sont gratuits ou s’ils sont soumis à des frais
- Le nombre de jours après l’achat pendant lesquels vous acceptez les retours, les remboursements ou les échanges
- La façon dont les clients peuvent retourner les articles qui leur ont été expédiés
- Si vous acceptez les retours en magasin
- Un lien vers la politique complète de retour et de remboursement
- Un message personnalisé.

Si vous acceptez les retours, les remboursements ou les échanges gratuits, Checkout met en évidence la politique pour les clients.

Les aperçus suivants montrent comment Checkout affiche une politique de retour. Dans cet exemple, les achats à retourner peuvent être expédiés ou ramenés en magasin pour un remboursement total ou un échange jusqu’à 60&nbsp;jours après l’achat. Vous pouvez afficher des informations similaires pour les remboursements.
![Aperçu des politiques de retour dans Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Aperçu des politiques de retour dans Checkout.
![Aperçu d’une politique mise en évidence dans Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Aperçu d’une politique mise en évidence dans Checkout.

#### Recueillir le consentement aux conditions d’utilisation du service

Les entreprises exigent souvent de leurs clients qu’ils acceptent leurs conditions d’utilisation du service avant de pouvoir payer. Cela peut dépendre du type de produit ou d’abonnement. Checkout vous aide à obtenir l’accord nécessaire en demandant à un client d’accepter vos conditions avant de payer.
![Recueillir le consentement aux conditions d'utilisation du service](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Recueillir le consentement aux conditions d’utilisation du service

Vous pouvez obtenir les conditions d’utilisation du service avec Stripe Checkout lorsque vous créez une session&nbsp;:

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

Lorsque le paramètre `consent_collection.terms_of_service='required'` est défini, Checkout affiche de manière dynamique une case à cocher pour demander le consentement du client concernant les conditions d’utilisation du service. Si le paramètre `consent_collection.terms_of_service='none'` est défini, Checkout n’affichera pas la case à cocher et n’obligera pas les clients à accepter les conditions d’utilisation du service. Avant d’exiger le consentement du client, définissez l’URL de vos conditions d’utilisation du service dans les [informations publiques](https://dashboard.stripe.com/settings/public) de votre entreprise. La définition d’une URL de politique de confidentialité est facultative. Checkout renvoie également vers votre politique de confidentialité si une URL de politique de confidentialité est définie dans vos [informations publiques](https://dashboard.stripe.com/settings/public).

Une fois qu’un client a finalisé son paiement, vous pouvez vérifier qu’il a accepté vos conditions d’utilisation du service en examinant l’objet Session dans le webhook `checkout.session.completed` ou en récupérant la session à l’aide de l’API. Lorsque les conditions sont acceptées, le champ [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) de la session est défini sur `accepted`.

Vous pouvez personnaliser le texte qui apparaît en regard de la case à cocher à l’aide de l’attribut `custom_text.terms_of_service_acceptance`. Vous devez définir `consent_collection.terms_of_service='required'`. Pour utiliser vos propres conditions, insérez un lien Markdown. Par exemple&nbsp;: `I agree to the [Terms of Service](https://example.com/terms)`

> Consultez vos conseillers juridiques et vos experts en conformité avant d’apporter des modifications à ce texte. Vous ne pouvez pas utiliser cette fonctionnalité pour afficher un texte personnalisé qui enfreint ou crée une ambiguïté par rapport au texte généré par Stripe dans Checkout, aux obligations découlant de votre contrat Stripe, aux politiques de Stripe et aux lois en vigueur.

#### Collect consent for promotional emails

Vous pouvez envoyer des courriels promotionnels pour informer les clients des nouveaux produits et proposer des bons de réduction et des remises. Avant de le faire, vous devez [demander leur consentement](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) aux courriels promotionnels.

## Personnaliser le contrat de réutilisation des modes de paiement et les conditions d’abonnement

Lorsqu’une session est en mode `setup` ou `subscription`, ou en mode `payment` avec `setup_future_usage` défini, Checkout affiche un message invitant à réutiliser le mode de paiement du client. Le message peut inclure des informations spécifiques au mode de paiement sélectionné. Vous pouvez masquer ou personnaliser le texte par défaut, mais pas le texte spécifique au mode de paiement.

Dans le cas d’un abonnement, le texte personnalisé peut inclure des informations telles que les suivantes&nbsp;:

- Un lien vers vos conditions d’abonnement
- Un lien vers votre portail client
- Mécanismes et politiques d’annulation
![Affichage du contrat de réutilisation des moyens de paiement par défaut en mode abonnement](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Contrat de réutilisation du moyen de paiement par défaut en mode abonnement

> En personnalisant ce texte, vous êtes responsable du maintien de la conformité, ce qui inclut la mise à jour de ce texte à mesure que les règles des réseaux de cartes et les réglementations locales évoluent. N’utilisez pas cette fonctionnalité sans consulter votre équipe juridique ou définir un texte personnalisé contenant les informations voulues relatives à la réutilisation du mode de paiement. Veillez à ce que votre texte personnalisé couvre tous les modes que vous comptez prendre en charge.

Pour masquer le texte de l’accord de réutilisation du mode de paiement, définissez `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout n’affichera pas les termes par défaut régissant la réutilisation du mode de paiement. Pour définir votre propre texte à la place des termes par défaut de Stripe, définissez `custom_text.after_submit.message`. Vous pouvez également utiliser `custom_text.submit` ou `custom_text.terms_of_service_acceptance` pour afficher votre propre version de ces termes.

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

> Il vous est interdit d’utiliser cette fonctionnalité pour créer un texte personnalisé qui entre en conflit ou crée une ambiguïté avec le texte généré par Stripe dans Checkout ou les obligations en vertu de votre contrat Stripe, les politiques de Stripe et les lois applicables.

```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"
```
![Texte personnalisé près de la collecte de l'adresse de livraison](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Texte personnalisé près des champs de collecte de l’adresse de livraison
![Texte personnalisé au-dessus du bouton Payer](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texte personnalisé au-dessus du bouton **Payer**
![Texte personnalisé sous le bouton Payer](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Texte personnalisé après le bouton **Payer**

Votre texte personnalisé peut comporter jusqu’à 1&nbsp;200&nbsp;caractères. Cependant, Stripe Checkout est optimisé pour la conversion et l’ajout d’informations supplémentaires peut affecter votre taux de conversion. Vous pouvez utilisez des caractères gras ou insérer un lien en utilisant la [syntaxe Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Pour mieux aligner Checkout sur votre modèle économique, configurez le texte affiché sur le bouton d’envoi Checkout pour les achats ponctuels.

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

## Localisation et langues prises en charge

Par défaut, Checkout détectera les paramètres régionaux du navigateur du client et affichera une version traduite de la page dans sa langue, si Stripe [la prend en charge](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Vous pouvez remplacer les paramètres régionaux du navigateur pour Checkout en transmettant le [paramètre](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` lorsque vous créez une session Checkout.

Checkout utilise également les paramètres régionaux pour formater les chiffres et les devises. Par exemple, lors de la vente d’un produit dont le prix est défini en EUR avec les paramètres régionaux définis sur `auto`, un navigateur configuré pour utiliser l’anglais (`en`) affichera €25.00, tandis qu’une configuration pour l’allemand (`de`) affichera 25,00&nbsp;€.

### Customize policies and contact information 

Vous pouvez afficher votre politique de retour et de remboursement, vos politiques juridiques, ainsi que les coordonnées de votre service d’assistance pour vos clients dans Checkout. Accédez aux [paramètres Checkout](https://dashboard.stripe.com/settings/checkout) pour configurer les informations que vous souhaitez afficher, y compris les éléments suivants&nbsp;:

- Détails concernant vos politiques de retour et de remboursement
- Site Web, adresse courriel et numéro de téléphone de votre service d’assistance
- Liens vers vos Conditions d’utilisation du service et votre Politique de confidentialité

Présentées clairement, ces informations peuvent mettre vos clients en confiance et réduire le taux d’abandon des paniers.

### Configurer le service d’assistance et les politiques juridiques

Dans les [paramètres Checkout](https://dashboard.stripe.com/settings/checkout), activez l’option **Coordonnées** pour ajouter les coordonnées du service d’assistance à vos sessions. De la même manière, ajoutez les liens vers vos **Conditions d’utilisation du service** et votre **Politique de confidentialité** après avoir activé l’option **Politiques juridiques**. Si vous demandez à vos clients de consentir implicitement à vos politiques juridiques lorsqu’ils effectuent leur paiement, cochez la case **Afficher le consentement aux conditions juridiques**.

Vous devez ajouter les liens vers les coordonnées de votre service d’assistance et vers vos politiques juridiques dans vos [paramètres d’informations publiques sur l’entreprise](https://dashboard.stripe.com/settings/public).

Les aperçus suivants montrent comment Checkout affiche une boîte de dialogue avec les coordonnées du service d’assistance, les liens vers les politiques juridiques, ainsi que les informations concernant les conditions de paiement.
![Une page de paiement avec des coordonnées.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Aperçu des coordonnées dans Checkout.
![Une page de paiement avec des politiques juridiques.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Aperçu des politiques juridiques dans Checkout.

### Configurez les politiques de retour et de remboursement

Activez l’option **Politiques de retour et de remboursement** pour afficher vos politiques de retour, de remboursement ou d’échange. Si les entreprises qui vendent des biens physiques utilisent des politiques de retour, celles qui vendent des biens numériques ou des biens physiques personnalisés utilisent généralement des politiques de remboursement. Comme elles ne s’excluent pas mutuellement, vous pouvez sélectionner les deux options si votre entreprise vend ces deux catégories de biens. Vous pouvez modifier les détails de vos retours et remboursements, en précisant notamment&nbsp;:

- Si vous acceptez les retours, les remboursements ou les échanges
- Si les retours, les remboursements ou les échanges sont gratuits ou s’ils sont soumis à des frais
- Le nombre de jours après l’achat pendant lesquels vous acceptez les retours, les remboursements ou les échanges
- La façon dont les clients peuvent retourner les articles qui leur ont été expédiés
- Si vous acceptez les retours en magasin
- Un lien vers la politique complète de retour et de remboursement
- Un message personnalisé.

Si vous acceptez les retours, les remboursements ou les échanges gratuits, Checkout met en évidence la politique pour les clients.

Les aperçus suivants montrent comment Checkout affiche une politique de retour. Dans cet exemple, les achats à retourner peuvent être expédiés ou ramenés en magasin pour un remboursement total ou un échange jusqu’à 60&nbsp;jours après l’achat. Vous pouvez afficher des informations similaires pour les remboursements.
![Aperçu des politiques de retour dans Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Aperçu des politiques de retour dans Checkout.
![Aperçu d’une politique mise en évidence dans Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Aperçu d’une politique mise en évidence dans Checkout.

#### Recueillir le consentement aux conditions d’utilisation du service

Les entreprises exigent souvent de leurs clients qu’ils acceptent leurs conditions d’utilisation du service avant de pouvoir payer. Cela peut dépendre du type de produit ou d’abonnement. Checkout vous aide à obtenir l’accord nécessaire en demandant à un client d’accepter vos conditions avant de payer.
![Recueillir le consentement aux conditions d'utilisation du service](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Recueillir le consentement aux conditions d’utilisation du service

Vous pouvez obtenir les conditions d’utilisation du service avec Stripe Checkout lorsque vous créez une session&nbsp;:

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

Lorsque le paramètre `consent_collection.terms_of_service='required'` est défini, Checkout affiche de manière dynamique une case à cocher pour demander le consentement du client concernant les conditions d’utilisation du service. Si le paramètre `consent_collection.terms_of_service='none'` est défini, Checkout n’affichera pas la case à cocher et n’obligera pas les clients à accepter les conditions d’utilisation du service. Avant d’exiger le consentement du client, définissez l’URL de vos conditions d’utilisation du service dans les [informations publiques](https://dashboard.stripe.com/settings/public) de votre entreprise. La définition d’une URL de politique de confidentialité est facultative. Checkout renvoie également vers votre politique de confidentialité si une URL de politique de confidentialité est définie dans vos [informations publiques](https://dashboard.stripe.com/settings/public).

Une fois qu’un client a finalisé son paiement, vous pouvez vérifier qu’il a accepté vos conditions d’utilisation du service en examinant l’objet Session dans le webhook `checkout.session.completed` ou en récupérant la session à l’aide de l’API. Lorsque les conditions sont acceptées, le champ [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) de la session est défini sur `accepted`.

Vous pouvez personnaliser le texte qui apparaît en regard de la case à cocher à l’aide de l’attribut `custom_text.terms_of_service_acceptance`. Vous devez définir `consent_collection.terms_of_service='required'`. Pour utiliser vos propres conditions, insérez un lien Markdown. Par exemple&nbsp;: `I agree to the [Terms of Service](https://example.com/terms)`

> Consultez vos conseillers juridiques et vos experts en conformité avant d’apporter des modifications à ce texte. Vous ne pouvez pas utiliser cette fonctionnalité pour afficher un texte personnalisé qui enfreint ou crée une ambiguïté par rapport au texte généré par Stripe dans Checkout, aux obligations découlant de votre contrat Stripe, aux politiques de Stripe et aux lois en vigueur.

#### Collect consent for promotional emails

Vous pouvez envoyer des courriels promotionnels pour informer les clients des nouveaux produits et proposer des bons de réduction et des remises. Avant de le faire, vous devez [demander leur consentement](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) aux courriels promotionnels.

## Personnaliser le contrat de réutilisation des modes de paiement et les conditions d’abonnement

Lorsqu’une session est en mode `setup` ou `subscription`, ou en mode `payment` avec `setup_future_usage` défini, Checkout affiche un message invitant à réutiliser le mode de paiement du client. Le message peut inclure des informations spécifiques au mode de paiement sélectionné. Vous pouvez masquer ou personnaliser le texte par défaut, mais pas le texte spécifique au mode de paiement.

Dans le cas d’un abonnement, le texte personnalisé peut inclure des informations telles que les suivantes&nbsp;:

- Un lien vers vos conditions d’abonnement
- Un lien vers votre portail client
- Mécanismes et politiques d’annulation
![Affichage du contrat de réutilisation des moyens de paiement par défaut en mode abonnement](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Contrat de réutilisation du moyen de paiement par défaut en mode abonnement

> En personnalisant ce texte, vous êtes responsable du maintien de la conformité, ce qui inclut la mise à jour de ce texte à mesure que les règles des réseaux de cartes et les réglementations locales évoluent. N’utilisez pas cette fonctionnalité sans consulter votre équipe juridique ou définir un texte personnalisé contenant les informations voulues relatives à la réutilisation du mode de paiement. Veillez à ce que votre texte personnalisé couvre tous les modes que vous comptez prendre en charge.

Pour masquer le texte de l’accord de réutilisation du mode de paiement, définissez `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout n’affichera pas les termes par défaut régissant la réutilisation du mode de paiement. Pour définir votre propre texte à la place des termes par défaut de Stripe, définissez `custom_text.after_submit.message`. Vous pouvez également utiliser `custom_text.submit` ou `custom_text.terms_of_service_acceptance` pour afficher votre propre version de ces termes.

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