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

> Non ti è consentito utilizzare questa funzione per creare testi personalizzati che violino o creino ambiguità con il testo generato da Stripe su Checkout, gli obblighi previsti dal contratto Stripe, le politiche di Stripe e le leggi vigenti.

```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"
```
![Testo personalizzato vicino alla raccolta degli indirizzi di spedizione](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Testo personalizzato vicino ai campi di raccolta dell’indirizzo di spedizione
![Testo personalizzato sopra il pulsante di pagamento](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Testo personalizzato sopra il pulsante **Paga**
![Testo personalizzato sotto il pulsante di pagamento](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Testo personalizzato dopo il pulsante **Paga**

Il testo personalizzato può contenere fino a 1200 caratteri. Tuttavia, Stripe Checkout è ottimizzato per la conversione e, pertanto, l’aggiunta di ulteriori informazioni potrebbe influire sul tasso di conversione. Puoi applicare il grassetto al testo o inserire un link utilizzando la [sintassi Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Per allineare Checkout al tuo modello di business, configura il testo visualizzato sul pulsante di invio di Checkout per gli acquisti una tantum.

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

## Localizzazione e lingue supportate

Per impostazione predefinita, Checkout rileva le impostazioni locali del browser del cliente e mostra una versione tradotta della pagina nella sua lingua, se Stripe [la supporta](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Puoi modificare le impostazioni locali del browser di Checkout specificando il [parametro](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` quando crei una sessione di Checkout.

Checkout utilizza inoltre le impostazioni locali per formattare numeri e valute. Ad esempio, se vendi un prodotto il cui prezzo è impostato in EUR con le impostazioni locali impostate su `auto`, in un browser configurato per utilizzare l’inglese (`en`) viene visualizzato come 25.00 € mentre in quello configurato per il tedesco (`de`) come 25,00 €.

### Customize policies and contact information 

Su Checkout puoi mostrare ai clienti le politiche di rimborso e reso, le norme legali e le informazioni di contatto dell’assistenza. Accedi a [Impostazioni di Checkout](https://dashboard.stripe.com/settings/checkout) per configurare le informazioni che vuoi visualizzare, tra cui:

- Dettagli delle politiche di rimborso e reso
- Numero di telefono, indirizzo email e sito web dell’assistenza
- Link ai termini di servizio e all’informativa sulla privacy

Mostrare queste informazioni può aumentare la fiducia dell’acquirente e ridurre l’abbandono del carrello.

### Configurare l’assistenza e le norme legali

Da [Impostazioni di Checkout](https://dashboard.stripe.com/settings/checkout), abilita **Informazioni di contatto** per aggiungere le informazioni di contatto per le tue sessioni. Analogamente, seleziona **Norme legali** per aggiungere i **Termini di servizio** e l’**Informativa sulla privacy** alle tue sessioni. Se vuoi che i clienti acconsentano implicitamente alle tue norme legali quando completano il pagamento, seleziona la casella di controllo **Visualizza l’accettazione delle norme legali**.

Devi aggiungere le informazioni di contatto dell’assistenza e i link delle norme legali nelle [impostazioni delle informazioni pubbliche](https://dashboard.stripe.com/settings/public).

Le seguenti anteprime mostrano come Checkout visualizza una finestra di dialogo con le informazioni di contatto dell’assistenza, i link alle norme legali del negozio e le informazioni sui termini di pagamento.
![Una pagina di pagamento con le informazioni di contatto.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Anteprima delle informazioni di contatto su Checkout
![Una pagina di pagamento con le norme legali.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Anteprima delle norme legali su Checkout

### Configurare le politiche di rimborso e reso

Per visualizzare le tue politiche di rimborso, reso o cambio, abilita **Politica di rimborso e reso**. Le attività che vendono beni materiali utilizzano le politiche di reso, mentre le aziende che vendono beni digitali o beni materiali personalizzati in genere utilizzano politiche di rimborso. Dato che non si escludono a vicenda, puoi selezionare entrambe le opzioni se la tua attività vende entrambe le categorie di beni. Puoi modificare i dettagli del reso e del rimborso, specificando ad esempio:

- Se accetti resi, rimborsi o cambi
- Se resi, rimborsi o cambi sono gratuiti o soggetti a commissioni
- Quanti giorni dopo un acquisto accetti resi, rimborsi o cambi
- Modalità di restituzione degli articoli spediti ai clienti
- Se accetti resi in negozio
- Un link alla politica completa di reso e rimborso
- Un messaggio personalizzato

Se accetti resi, rimborsi o cambi gratuiti, Checkout mette in evidenza la politica per i clienti.

Le seguenti anteprime mostrano come Checkout visualizza una politica di reso. In questo esempio, gli acquisti da restituire possono essere spediti o resi in negozio per un rimborso totale (o un cambio) fino a 60 giorni dall’acquisto. Puoi visualizzare informazioni analoghe per i rimborsi.
![Anteprima delle politiche di reso su Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Anteprima delle politiche di reso su Checkout
![Anteprima di una politica in evidenza su Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Anteprima di una politica in evidenza su Checkout

#### Raccogliere il consenso per i termini di servizio

Le attività spesso chiedono ai propri clienti di accettare i termini di servizio prima di poter pagare. Potrebbe dipendere dal tipo di prodotto o di abbonamento. Checkout ti aiuta a raccogliere il consenso necessario richiedendo al cliente di accettare i tuoi termini prima di pagare.
![Raccogliere il consenso per i termini di servizio](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Raccogliere il consenso per i termini di servizio

Puoi raccogliere il consenso per termini di servizio con Stripe Checkout quando crei una sessione:

```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'`, Checkout visualizza in modo dinamico una casella di controllo per la raccolta del consenso sui termini di servizio del cliente. Se `consent_collection.terms_of_service='none'`, Checkout non visualizzerà la casella di controllo e non richiederà ai clienti di accettare i termini di servizio. Prima di richiedere l’accettazione dei termini, imposta l’URL dei termini di servizio nei [dati pubblici](https://dashboard.stripe.com/settings/public) della tua attività. L’impostazione di un URL dell’informativa sulla privacy è facoltativa: Checkout rimanda alla tua informativa sulla privacy anche quando un URL alla tua informativa sulla privacy è impostato nei [dati pubblici](https://dashboard.stripe.com/settings/public).

Una volta che il cliente ha completato la transazione, puoi verificare se ha accettato i tuoi termini di servizio esaminando l’oggetto Session nel webhook `checkout.session.completed` o recuperando la sessione utilizzando l’API. Quando i termini vengono accettati, il campo [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) della sessione è impostato su `accepted`.

Puoi personalizzare il testo visualizzato accanto alla casella di controllo utilizzando `custom_text.terms_of_service_acceptance`. Devi impostare `consent_collection.terms_of_service='required'`. Per collegare i tuoi termini di servizio, inserisci un link con linguaggio Markdown. Ad esempio: `I agree to the [Terms of Service](https://example.com/terms)`

> Rivolgiti ai tuoi consulenti legali e di conformità prima di apportare qualsiasi modifica a questo testo. Non puoi utilizzare questa funzione per visualizzare testi personalizzati che violino o creino ambiguità rispetto al testo generato da Stripe su Checkout, agli obblighi contrattuali con Stripe, alle politiche di Stripe o alle leggi vigenti.

#### Collect consent for promotional emails

Puoi inviare email promozionali per informare i clienti di nuovi prodotti e per condividere coupon e sconti. Prima di farlo, devi [raccogliere il loro consenso](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) a ricevere email promozionali.

## Personalizzare il contratto di riutilizzo dei metodi di pagamento e i termini di abbonamento

Quando una sessione è in modalità `setup` o `subscription` oppure in modalità `payment` con `setup_future_usage` impostato, Checkout mostra un messaggio sul riutilizzo del metodo di pagamento del cliente. Il messaggio può includere informazioni specifiche per il metodo di pagamento selezionato. Puoi nascondere o personalizzare il testo predefinito, ma non quello specifico del metodo di pagamento.

Per un abbonamento, il testo personalizzato può includere informazioni come le seguenti:

- Un link ai termini del tuo abbonamento
- Un link al tuo portale cliente
- Meccanismi e politiche di annullamento
![Visualizzazione del contratto di riutilizzo del metodo di pagamento predefinito in modalità abbonamento](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Contratto di riutilizzo del metodo di pagamento predefinito in modalità abbonamento

> Se personalizzi questo testo, sei responsabile del mantenimento della conformità, il che include l’aggiornamento del testo in base alle modifiche delle regole dei circuiti delle carte e delle normative locali. Non utilizzare questa funzione senza consultare il tuo team legale o impostare un testo personalizzato che includa informazioni sul riutilizzo del metodo di pagamento. Assicurati che il testo personalizzato copra tutti i metodi che intendi supportare.

Per nascondere il testo del contratto di riutilizzo del metodo di pagamento, imposta `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout non mostrerà la lingua predefinita che regola il riutilizzo del metodo di pagamento. Per impostare il tuo testo al posto della lingua predefinita di Stripe, imposta `custom_text.after_submit.message`. Puoi anche utilizzare `custom_text.submit` o `custom_text.terms_of_service_acceptance` per visualizzare la tua versione di questa lingua.

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

> Non ti è consentito utilizzare questa funzione per creare testi personalizzati che violino o creino ambiguità con il testo generato da Stripe su Checkout, gli obblighi previsti dal contratto Stripe, le politiche di Stripe e le leggi vigenti.

```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"
```
![Testo personalizzato vicino alla raccolta degli indirizzi di spedizione](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Testo personalizzato vicino ai campi di raccolta dell’indirizzo di spedizione
![Testo personalizzato sopra il pulsante di pagamento](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Testo personalizzato sopra il pulsante **Paga**
![Testo personalizzato sotto il pulsante di pagamento](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Testo personalizzato dopo il pulsante **Paga**

Il testo personalizzato può contenere fino a 1200 caratteri. Tuttavia, Stripe Checkout è ottimizzato per la conversione e, pertanto, l’aggiunta di ulteriori informazioni potrebbe influire sul tasso di conversione. Puoi applicare il grassetto al testo o inserire un link utilizzando la [sintassi Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Per allineare Checkout al tuo modello di business, configura il testo visualizzato sul pulsante di invio di Checkout per gli acquisti una tantum.

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

## Localizzazione e lingue supportate

Per impostazione predefinita, Checkout rileva le impostazioni locali del browser del cliente e mostra una versione tradotta della pagina nella sua lingua, se Stripe [la supporta](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Puoi modificare le impostazioni locali del browser di Checkout specificando il [parametro](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` quando crei una sessione di Checkout.

Checkout utilizza inoltre le impostazioni locali per formattare numeri e valute. Ad esempio, se vendi un prodotto il cui prezzo è impostato in EUR con le impostazioni locali impostate su `auto`, in un browser configurato per utilizzare l’inglese (`en`) viene visualizzato come 25.00 € mentre in quello configurato per il tedesco (`de`) come 25,00 €.

### Customize policies and contact information 

Su Checkout puoi mostrare ai clienti le politiche di rimborso e reso, le norme legali e le informazioni di contatto dell’assistenza. Accedi a [Impostazioni di Checkout](https://dashboard.stripe.com/settings/checkout) per configurare le informazioni che vuoi visualizzare, tra cui:

- Dettagli delle politiche di rimborso e reso
- Numero di telefono, indirizzo email e sito web dell’assistenza
- Link ai termini di servizio e all’informativa sulla privacy

Mostrare queste informazioni può aumentare la fiducia dell’acquirente e ridurre l’abbandono del carrello.

### Configurare l’assistenza e le norme legali

Da [Impostazioni di Checkout](https://dashboard.stripe.com/settings/checkout), abilita **Informazioni di contatto** per aggiungere le informazioni di contatto per le tue sessioni. Analogamente, seleziona **Norme legali** per aggiungere i **Termini di servizio** e l’**Informativa sulla privacy** alle tue sessioni. Se vuoi che i clienti acconsentano implicitamente alle tue norme legali quando completano il pagamento, seleziona la casella di controllo **Visualizza l’accettazione delle norme legali**.

Devi aggiungere le informazioni di contatto dell’assistenza e i link delle norme legali nelle [impostazioni delle informazioni pubbliche](https://dashboard.stripe.com/settings/public).

Le seguenti anteprime mostrano come Checkout visualizza una finestra di dialogo con le informazioni di contatto dell’assistenza, i link alle norme legali del negozio e le informazioni sui termini di pagamento.
![Una pagina di pagamento con le informazioni di contatto.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Anteprima delle informazioni di contatto su Checkout
![Una pagina di pagamento con le norme legali.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Anteprima delle norme legali su Checkout

### Configurare le politiche di rimborso e reso

Per visualizzare le tue politiche di rimborso, reso o cambio, abilita **Politica di rimborso e reso**. Le attività che vendono beni materiali utilizzano le politiche di reso, mentre le aziende che vendono beni digitali o beni materiali personalizzati in genere utilizzano politiche di rimborso. Dato che non si escludono a vicenda, puoi selezionare entrambe le opzioni se la tua attività vende entrambe le categorie di beni. Puoi modificare i dettagli del reso e del rimborso, specificando ad esempio:

- Se accetti resi, rimborsi o cambi
- Se resi, rimborsi o cambi sono gratuiti o soggetti a commissioni
- Quanti giorni dopo un acquisto accetti resi, rimborsi o cambi
- Modalità di restituzione degli articoli spediti ai clienti
- Se accetti resi in negozio
- Un link alla politica completa di reso e rimborso
- Un messaggio personalizzato

Se accetti resi, rimborsi o cambi gratuiti, Checkout mette in evidenza la politica per i clienti.

Le seguenti anteprime mostrano come Checkout visualizza una politica di reso. In questo esempio, gli acquisti da restituire possono essere spediti o resi in negozio per un rimborso totale (o un cambio) fino a 60 giorni dall’acquisto. Puoi visualizzare informazioni analoghe per i rimborsi.
![Anteprima delle politiche di reso su Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Anteprima delle politiche di reso su Checkout
![Anteprima di una politica in evidenza su Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Anteprima di una politica in evidenza su Checkout

#### Raccogliere il consenso per i termini di servizio

Le attività spesso chiedono ai propri clienti di accettare i termini di servizio prima di poter pagare. Potrebbe dipendere dal tipo di prodotto o di abbonamento. Checkout ti aiuta a raccogliere il consenso necessario richiedendo al cliente di accettare i tuoi termini prima di pagare.
![Raccogliere il consenso per i termini di servizio](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Raccogliere il consenso per i termini di servizio

Puoi raccogliere il consenso per termini di servizio con Stripe Checkout quando crei una sessione:

```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'`, Checkout visualizza in modo dinamico una casella di controllo per la raccolta del consenso sui termini di servizio del cliente. Se `consent_collection.terms_of_service='none'`, Checkout non visualizzerà la casella di controllo e non richiederà ai clienti di accettare i termini di servizio. Prima di richiedere l’accettazione dei termini, imposta l’URL dei termini di servizio nei [dati pubblici](https://dashboard.stripe.com/settings/public) della tua attività. L’impostazione di un URL dell’informativa sulla privacy è facoltativa: Checkout rimanda alla tua informativa sulla privacy anche quando un URL alla tua informativa sulla privacy è impostato nei [dati pubblici](https://dashboard.stripe.com/settings/public).

Una volta che il cliente ha completato la transazione, puoi verificare se ha accettato i tuoi termini di servizio esaminando l’oggetto Session nel webhook `checkout.session.completed` o recuperando la sessione utilizzando l’API. Quando i termini vengono accettati, il campo [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) della sessione è impostato su `accepted`.

Puoi personalizzare il testo visualizzato accanto alla casella di controllo utilizzando `custom_text.terms_of_service_acceptance`. Devi impostare `consent_collection.terms_of_service='required'`. Per collegare i tuoi termini di servizio, inserisci un link con linguaggio Markdown. Ad esempio: `I agree to the [Terms of Service](https://example.com/terms)`

> Rivolgiti ai tuoi consulenti legali e di conformità prima di apportare qualsiasi modifica a questo testo. Non puoi utilizzare questa funzione per visualizzare testi personalizzati che violino o creino ambiguità rispetto al testo generato da Stripe su Checkout, agli obblighi contrattuali con Stripe, alle politiche di Stripe o alle leggi vigenti.

#### Collect consent for promotional emails

Puoi inviare email promozionali per informare i clienti di nuovi prodotti e per condividere coupon e sconti. Prima di farlo, devi [raccogliere il loro consenso](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) a ricevere email promozionali.

## Personalizzare il contratto di riutilizzo dei metodi di pagamento e i termini di abbonamento

Quando una sessione è in modalità `setup` o `subscription` oppure in modalità `payment` con `setup_future_usage` impostato, Checkout mostra un messaggio sul riutilizzo del metodo di pagamento del cliente. Il messaggio può includere informazioni specifiche per il metodo di pagamento selezionato. Puoi nascondere o personalizzare il testo predefinito, ma non quello specifico del metodo di pagamento.

Per un abbonamento, il testo personalizzato può includere informazioni come le seguenti:

- Un link ai termini del tuo abbonamento
- Un link al tuo portale cliente
- Meccanismi e politiche di annullamento
![Visualizzazione del contratto di riutilizzo del metodo di pagamento predefinito in modalità abbonamento](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Contratto di riutilizzo del metodo di pagamento predefinito in modalità abbonamento

> Se personalizzi questo testo, sei responsabile del mantenimento della conformità, il che include l’aggiornamento del testo in base alle modifiche delle regole dei circuiti delle carte e delle normative locali. Non utilizzare questa funzione senza consultare il tuo team legale o impostare un testo personalizzato che includa informazioni sul riutilizzo del metodo di pagamento. Assicurati che il testo personalizzato copra tutti i metodi che intendi supportare.

Per nascondere il testo del contratto di riutilizzo del metodo di pagamento, imposta `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout non mostrerà la lingua predefinita che regola il riutilizzo del metodo di pagamento. Per impostare il tuo testo al posto della lingua predefinita di Stripe, imposta `custom_text.after_submit.message`. Puoi anche utilizzare `custom_text.submit` o `custom_text.terms_of_service_acceptance` per visualizzare la tua versione di questa lingua.

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