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

> No tienes permitido utilizar esta función para crear texto personalizado que infrinja o cree ambigüedad con el texto generado por Stripe en Checkout, las obligaciones en virtud del contrato de Stripe, las políticas de Stripe y las leyes aplicables.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  --data-urlencode "success_url=https://example.com/success"
```
![Texto personalizado cerca de la recopilación de direcciones de envío](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Texto personalizado cerca de los campos de recopilación de direcciones de envío
![Texto personalizado encima del botón de pago](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texto personalizado encima del botón **Paga**
![Texto personalizado debajo del botón de pago](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Texto personalizado después del botón **Paga**

Tu texto personalizado puede tener hasta 1200 caracteres. Sin embargo, Stripe Checkout está optimizado para la conversión y, si se añade información adicional, tu tasa de conversión podría verse afectada. Puedes poner el texto en negrita o insertar un vínculo mediante la [sintaxis de Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Para que el proceso de compra se adapte mejor a tu modelo de negocio, configura el texto que aparece en el botón de envío del proceso de compra para compras puntuales.

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

## Configuración regional e idiomas aceptados

De forma predeterminada, Checkout detecta la configuración regional del navegador del cliente y muestra una versión traducida de la página en su idioma, si Stripe [lo admite](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Puedes anular la configuración regional del navegador para Checkout transfiriendo el [parámetro](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` al crear una sesión de Checkout.

Checkout también usa la configuración regional para dar formato a los números y las divisas. Por ejemplo, cuando se vende un producto cuyo precio está definido en EUR con la configuración regional establecida en `auto`, un navegador configurado para usar inglés (`en`) mostraría «€25.00» mientras que uno configurado para alemán (`de`) mostraría «25,00&nbsp;€».

### Customize policies and contact information 

Puedes mostrarles a tus clientes las políticas legales, de devoluciones y rembolsos, así como la información de contacto del soporte en Checkout. Ve a [Configuración de Checkout](https://dashboard.stripe.com/settings/checkout) para configurar la información que quieres mostrar, incluyendo lo siguiente:

- Detalles sobre tus políticas de devoluciones y reembolsos
- Tu número de teléfono móvil de soporte, correo electrónico y sitio web
- Enlaces a las condiciones de servicio y la política de privacidad

Ofrecer esta información aumenta la confianza de los compradores y minimiza el abandono del carrito de compra.

### Configurar las políticas legales y de soporte

Desde la [configuración de Checkout](https://dashboard.stripe.com/settings/checkout), habilita **Información de contacto** para añadir información de contacto de soporte a tus sesiones. Del mismo modo, añade enlaces a tus **Condiciones de servicio** y tu **Política de privacidad** en tus sesiones habilitando las **Políticas legales**. Si les solicitas a tus clientes que acepten tus políticas legales de manera implícita cuando completan el proceso de compra, selecciona la casilla **Mostrar la aceptación de las condiciones legales**.

Debes añadir los enlaces de la información de contacto de soporte y las políticas legales en la [Configuración de datos públicos](https://dashboard.stripe.com/settings/public).

Las siguientes vistas previas muestran el diálogo que presenta Checkout con la información de contacto de soporte, los enlaces a las políticas legales de la tienda y la información sobre las condiciones de pago.
![Una página del proceso de compra con información de contacto.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Previsualización de la información de contacto en Checkout.
![Una página del proceso de compra con políticas legales.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Previsualización de las políticas legales en Checkout.

### Configura las políticas de devoluciones y reembolsos

Muestra tus políticas de devoluciones, rembolsos o cambios habilitando **Políticas de devoluciones y rembolsos**. Mientras que las empresas que venden bienes tangibles utilizan políticas de devoluciones, las empresas que venden productos digitales o bienes tangibles personalizados normalmente utilizan políticas de reembolsos. Debido a que no se excluyen mutuamente, puedes seleccionar ambas opciones si tu empresa vende ambas categorías de productos. Puedes modificar los datos de tus devoluciones y reembolsos, lo que incluye:

- Si aceptas devoluciones, reembolsos o cambios
- Si las devoluciones, reembolsos o cambios son gratuitos o están sujetos a una comisión
- Cuántos días después de la compra aceptas devoluciones, reembolsos o cambios
- Cómo pueden los clientes devolver los artículos recibidos
- Si aceptas devoluciones en la tienda
- Un enlace al texto completo de la política de devoluciones y reembolsos
- Un mensaje personalizado

Si aceptas devoluciones, reembolsos o cambios gratuitos, Checkout resalta la política para que la vean los clientes.

Las siguientes vistas previas muestran cómo presenta Checkout una política de devoluciones. En este ejemplo, se trata de productos comprados que pueden devolverse mediante envío o en la tienda a cambio de un reembolso completo (o la sustitución del producto) en un plazo máximo de 60 días. Puedes mostrar información similar para los reembolsos.
![Previsualización de las políticas de devolución en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Previsualización de las políticas de devolución en Checkout.
![Vista previa de una política destacada en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Previsualización de un aspecto destacado de la política en Checkout.

#### Obtener un contrato de condiciones de servicio

Las empresas a menudo requieren que sus clientes acepten sus condiciones de servicio antes de poder pagar. Esto puede depender del tipo de producto o suscripción. Checkout te ayuda a obtener el acuerdo necesario al exigir a los clientes que acepten tus términos antes de pagar.
![Obtener contrato de condiciones de servicio](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Obtener contrato de condiciones de servicio

Puedes obtener un acuerdo de condiciones de servicio con Stripe Checkout al crear una sesión:

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

Cuando `consent_collection.terms_of_service='required'`, Checkout muestra dinámicamente una casilla de verificación para recopilar el contrato de condiciones de servicio del cliente. Si `consent_collection.terms_of_service='none'`, Checkout no mostrará la casilla de verificación y no requerirá que los clientes acepten las condiciones de servicio. Antes de solicitar la aceptación de tus condiciones, establece la URL de las condiciones de servicio en los [datos públicos](https://dashboard.stripe.com/settings/public) de tu empresa. Configurar una URL de política de privacidad es opcional. Checkout también se vincula a tu política de privacidad cuando se establece una URL a tu política de privacidad en tus [datos públicos](https://dashboard.stripe.com/settings/public).

Cuando un cliente completa el proceso de pago, puedes comprobar si el cliente ha aceptado tus condiciones de servicio consultando el objeto Session en el webhook `checkout.session.completed`checkout.session.completed’ o recuperando la Session mediante la API. Cuando se aceptan las condiciones, el campo [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) de la sesión se establece en `accepted`.

Puedes personalizar el texto que aparece junto a la casilla de verificación usando `custom_text.terms_of_service_acceptance`. Debes configurar `consent_collection.terms_of_service='required'`. Para usar tus propias condiciones, inserta un enlace de Markdown. Por ejemplo: `I agree to the [Terms of Service](https://example.com/terms)`

> Consulta a tus asesores legales y de cumplimiento de la normativa antes de realizar cualquier cambio en este texto. No puedes usar esta función para mostrar texto personalizado que infrinja o cree ambigüedad con el texto generado por Stripe en Checkout, las obligaciones en virtud de tu contrato de Stripe, las políticas de Stripe y las leyes aplicables.

#### Collect consent for promotional emails

Puedes enviar correos electrónicos promocionales para informar a los clientes sobre nuevos productos y compartir cupones y descuentos. Antes de hacerlo, debes [obtener su consentimiento](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) para recibir correos electrónicos promocionales.

## Personaliza el acuerdo de reutilización del método de pago y las condiciones de suscripción

Cuando una sesión está en modo `setup` o `subscription`, o está en modo `payment` con `setup_future_usage` establecido, Checkout muestra un mensaje sobre la reutilización del método de pago del cliente. El mensaje puede incluir información específica del método de pago elegido. Puedes ocultar o personalizar el texto predeterminado, pero no el texto específico del método de pago.

En el caso de una suscripción, el texto personalizado puede incluir información como la siguiente:

- Enlace a las condiciones de tu suscripción
- Enlace a tu portal de clientes
- Mecanismos y políticas de cancelación
![Visualización del acuerdo de reutilización de métodos de pago predeterminados en el modo de suscripción](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Acuerdo de reutilización de métodos de pago predeterminado en el modo de suscripción

> Al personalizar este texto, eres responsable de mantener el cumplimiento de la normativa, lo que incluye actualizar este texto a medida que cambien las reglas de las redes de tarjetas y la normativa local. No utilices esta función sin consultar con tu equipo legal o sin configurar un texto personalizado que incluya información sobre la reutilización del método de pago. Asegúrate de que tu texto personalizado abarque todos los modos que planeas admitir.

Para ocultar el texto del acuerdo de reutilización de métodos de pago, establece `consent_collection.payment_method_reuse_agreement.position='hidden'`. El Checkout no mostrará el idioma predeterminado que rige la reutilización del método de pago. Para establecer tu propio texto en lugar del idioma predeterminado de Stripe, establece `custom_text.after_submit.message`. También puedes usar `custom_text.submit` o `custom_text.terms_of_service_acceptance` para mostrar tu propia versión de este idioma.

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


# Embedded page

> This is a Embedded page for when platform is web and payment-ui is embedded-form. View the full page at https://docs.stripe.com/payments/checkout/custom-components?platform=web&payment-ui=embedded-form.

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

## Add custom fields 

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

Custom fields have the following limitations:

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

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

### Create a Checkout Session 

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text"
```
![](https://d37ugbyn3rpeym.cloudfront.net/videos/checkout/custom_fields_embedded.mov)
### Retrieve custom fields 

When your customer completes the Checkout Session, we send a [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) with the completed fields.

Example `checkout.session.completed` payload:

```json
{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1664928000,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session","custom_fields": [{
        "key": "engraving",
        "label": {
          "type": "custom",
          "custom": "Personalized engraving"
        },
        "optional": false,
        "type": "text",
        "text": {
          "value": "Jane"
        }
      }],
      "mode": "payment"
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}
```

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

### Use a custom field 

#### Mark a field as optional 

By default, customers must complete all fields before completing payment. To mark a field as optional, pass in `optional=true`.

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

#### Add a dropdown field 

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

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=sample" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Free sample" \
  -d "custom_fields[0][optional]=true" \
  -d "custom_fields[0][type]=dropdown" \
  -d "custom_fields[0][dropdown][options][0][label]=Balm sample" \
  -d "custom_fields[0][dropdown][options][0][value]=balm" \
  -d "custom_fields[0][dropdown][options][1][label]=BB cream sample" \
  -d "custom_fields[0][dropdown][options][1][value]=cream"
```
![A checkout page with a dropdown field](https://b.stripecdn.com/docs-statics-srv/assets/dropdown.4501d199ebe009030c2be6935cfdf2dd.png)

#### Add a numbers only field 

A numbers-only field provides your customers a text field that only accepts numerical values, up to 255 digits. To create a numbers-only field, specify `type=numeric`.

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

#### Retrieve custom fields for a subscription 

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

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

#### Add character length validations 

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

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

#### Add default values 

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

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

## Customize text and policies 

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

> No tienes permitido utilizar esta función para crear texto personalizado que infrinja o cree ambigüedad con el texto generado por Stripe en Checkout, las obligaciones en virtud del contrato de Stripe, las políticas de Stripe y las leyes aplicables.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```
![Texto personalizado cerca de la recopilación de direcciones de envío](https://b.stripecdn.com/docs-statics-srv/assets/shipping-address-custom-text.b0b578d66d2bd415d0b0fe03106d27df.png)

Texto personalizado cerca de los campos de recopilación de direcciones de envío
![Texto personalizado encima del botón de pago](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texto personalizado encima del botón **Paga**
![Texto personalizado debajo del botón de pago](https://b.stripecdn.com/docs-statics-srv/assets/custom-text-after-submit.32dbd97008b3f189145bcd07c4562bb4.png)

Texto personalizado después del botón **Paga**

Tu texto personalizado puede tener hasta 1200 caracteres. Sin embargo, Stripe Checkout está optimizado para la conversión y, si se añade información adicional, tu tasa de conversión podría verse afectada. Puedes poner el texto en negrita o insertar un vínculo mediante la [sintaxis de Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Para que el proceso de compra se adapte mejor a tu modelo de negocio, configura el texto que aparece en el botón de envío del proceso de compra para compras puntuales.

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

## Configuración regional e idiomas aceptados

De forma predeterminada, Checkout detecta la configuración regional del navegador del cliente y muestra una versión traducida de la página en su idioma, si Stripe [lo admite](https://support.stripe.com/questions/supported-languages-for-stripe-checkout). Puedes anular la configuración regional del navegador para Checkout transfiriendo el [parámetro](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) `locale` al crear una sesión de Checkout.

Checkout también usa la configuración regional para dar formato a los números y las divisas. Por ejemplo, cuando se vende un producto cuyo precio está definido en EUR con la configuración regional establecida en `auto`, un navegador configurado para usar inglés (`en`) mostraría «€25.00» mientras que uno configurado para alemán (`de`) mostraría «25,00&nbsp;€».

### Customize policies and contact information 

Puedes mostrarles a tus clientes las políticas legales, de devoluciones y rembolsos, así como la información de contacto del soporte en Checkout. Ve a [Configuración de Checkout](https://dashboard.stripe.com/settings/checkout) para configurar la información que quieres mostrar, incluyendo lo siguiente:

- Detalles sobre tus políticas de devoluciones y reembolsos
- Tu número de teléfono móvil de soporte, correo electrónico y sitio web
- Enlaces a las condiciones de servicio y la política de privacidad

Ofrecer esta información aumenta la confianza de los compradores y minimiza el abandono del carrito de compra.

### Configurar las políticas legales y de soporte

Desde la [configuración de Checkout](https://dashboard.stripe.com/settings/checkout), habilita **Información de contacto** para añadir información de contacto de soporte a tus sesiones. Del mismo modo, añade enlaces a tus **Condiciones de servicio** y tu **Política de privacidad** en tus sesiones habilitando las **Políticas legales**. Si les solicitas a tus clientes que acepten tus políticas legales de manera implícita cuando completan el proceso de compra, selecciona la casilla **Mostrar la aceptación de las condiciones legales**.

Debes añadir los enlaces de la información de contacto de soporte y las políticas legales en la [Configuración de datos públicos](https://dashboard.stripe.com/settings/public).

Las siguientes vistas previas muestran el diálogo que presenta Checkout con la información de contacto de soporte, los enlaces a las políticas legales de la tienda y la información sobre las condiciones de pago.
![Una página del proceso de compra con información de contacto.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

Previsualización de la información de contacto en Checkout.
![Una página del proceso de compra con políticas legales.](https://b.stripecdn.com/docs-statics-srv/assets/legal-modal.9351cb51408c2a9f5c0ae23aab03e138.png)

Previsualización de las políticas legales en Checkout.

### Configura las políticas de devoluciones y reembolsos

Muestra tus políticas de devoluciones, rembolsos o cambios habilitando **Políticas de devoluciones y rembolsos**. Mientras que las empresas que venden bienes tangibles utilizan políticas de devoluciones, las empresas que venden productos digitales o bienes tangibles personalizados normalmente utilizan políticas de reembolsos. Debido a que no se excluyen mutuamente, puedes seleccionar ambas opciones si tu empresa vende ambas categorías de productos. Puedes modificar los datos de tus devoluciones y reembolsos, lo que incluye:

- Si aceptas devoluciones, reembolsos o cambios
- Si las devoluciones, reembolsos o cambios son gratuitos o están sujetos a una comisión
- Cuántos días después de la compra aceptas devoluciones, reembolsos o cambios
- Cómo pueden los clientes devolver los artículos recibidos
- Si aceptas devoluciones en la tienda
- Un enlace al texto completo de la política de devoluciones y reembolsos
- Un mensaje personalizado

Si aceptas devoluciones, reembolsos o cambios gratuitos, Checkout resalta la política para que la vean los clientes.

Las siguientes vistas previas muestran cómo presenta Checkout una política de devoluciones. En este ejemplo, se trata de productos comprados que pueden devolverse mediante envío o en la tienda a cambio de un reembolso completo (o la sustitución del producto) en un plazo máximo de 60 días. Puedes mostrar información similar para los reembolsos.
![Previsualización de las políticas de devolución en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

Previsualización de las políticas de devolución en Checkout.
![Vista previa de una política destacada en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/policy-highlight.334828420693a33d376977a2c0fe5851.png)

Previsualización de un aspecto destacado de la política en Checkout.

#### Obtener un contrato de condiciones de servicio

Las empresas a menudo requieren que sus clientes acepten sus condiciones de servicio antes de poder pagar. Esto puede depender del tipo de producto o suscripción. Checkout te ayuda a obtener el acuerdo necesario al exigir a los clientes que acepten tus términos antes de pagar.
![Obtener contrato de condiciones de servicio](https://b.stripecdn.com/docs-statics-srv/assets/terms-of-service-consent-collection.dec90bde6d1a3c5d4c0b3e7b8e644a52.png)

Obtener contrato de condiciones de servicio

Puedes obtener un acuerdo de condiciones de servicio con Stripe Checkout al crear una sesión:

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

Cuando `consent_collection.terms_of_service='required'`, Checkout muestra dinámicamente una casilla de verificación para recopilar el contrato de condiciones de servicio del cliente. Si `consent_collection.terms_of_service='none'`, Checkout no mostrará la casilla de verificación y no requerirá que los clientes acepten las condiciones de servicio. Antes de solicitar la aceptación de tus condiciones, establece la URL de las condiciones de servicio en los [datos públicos](https://dashboard.stripe.com/settings/public) de tu empresa. Configurar una URL de política de privacidad es opcional. Checkout también se vincula a tu política de privacidad cuando se establece una URL a tu política de privacidad en tus [datos públicos](https://dashboard.stripe.com/settings/public).

Cuando un cliente completa el proceso de pago, puedes comprobar si el cliente ha aceptado tus condiciones de servicio consultando el objeto Session en el webhook `checkout.session.completed`checkout.session.completed’ o recuperando la Session mediante la API. Cuando se aceptan las condiciones, el campo [consent.terms_of_service](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-consent) de la sesión se establece en `accepted`.

Puedes personalizar el texto que aparece junto a la casilla de verificación usando `custom_text.terms_of_service_acceptance`. Debes configurar `consent_collection.terms_of_service='required'`. Para usar tus propias condiciones, inserta un enlace de Markdown. Por ejemplo: `I agree to the [Terms of Service](https://example.com/terms)`

> Consulta a tus asesores legales y de cumplimiento de la normativa antes de realizar cualquier cambio en este texto. No puedes usar esta función para mostrar texto personalizado que infrinja o cree ambigüedad con el texto generado por Stripe en Checkout, las obligaciones en virtud de tu contrato de Stripe, las políticas de Stripe y las leyes aplicables.

#### Collect consent for promotional emails

Puedes enviar correos electrónicos promocionales para informar a los clientes sobre nuevos productos y compartir cupones y descuentos. Antes de hacerlo, debes [obtener su consentimiento](https://docs.stripe.com/payments/checkout/promotional-emails-consent.md) para recibir correos electrónicos promocionales.

## Personaliza el acuerdo de reutilización del método de pago y las condiciones de suscripción

Cuando una sesión está en modo `setup` o `subscription`, o está en modo `payment` con `setup_future_usage` establecido, Checkout muestra un mensaje sobre la reutilización del método de pago del cliente. El mensaje puede incluir información específica del método de pago elegido. Puedes ocultar o personalizar el texto predeterminado, pero no el texto específico del método de pago.

En el caso de una suscripción, el texto personalizado puede incluir información como la siguiente:

- Enlace a las condiciones de tu suscripción
- Enlace a tu portal de clientes
- Mecanismos y políticas de cancelación
![Visualización del acuerdo de reutilización de métodos de pago predeterminados en el modo de suscripción](https://b.stripecdn.com/docs-statics-srv/assets/default-subscription-mode-payment-method-reuse-agreement.caee311155d9948637a53aafded801af.png)

Acuerdo de reutilización de métodos de pago predeterminado en el modo de suscripción

> Al personalizar este texto, eres responsable de mantener el cumplimiento de la normativa, lo que incluye actualizar este texto a medida que cambien las reglas de las redes de tarjetas y la normativa local. No utilices esta función sin consultar con tu equipo legal o sin configurar un texto personalizado que incluya información sobre la reutilización del método de pago. Asegúrate de que tu texto personalizado abarque todos los modos que planeas admitir.

Para ocultar el texto del acuerdo de reutilización de métodos de pago, establece `consent_collection.payment_method_reuse_agreement.position='hidden'`. El Checkout no mostrará el idioma predeterminado que rige la reutilización del método de pago. Para establecer tu propio texto en lugar del idioma predeterminado de Stripe, establece `custom_text.after_submit.message`. También puedes usar `custom_text.submit` o `custom_text.terms_of_service_acceptance` para mostrar tu propia versión de este idioma.

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


# Checkout elements

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

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