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

> Se prohíbe el uso de esta funcionalidad para crear texto personalizado que infrinja o cree ambigüedad con el texto generado por Stripe en Checkout, las obligaciones en virtud de tu contrato con Stripe, las políticas de Stripe y la legislación aplicable.

```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 la dirección de envío
![Texto personalizado arriba del botón de pago](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texto personalizado arriba del botón **Pagar**
![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 **Pagar**

El texto personalizado puede tener una longitud máxima de 1200 caracteres. Sin embargo, Stripe Checkout está optimizado para la conversión, y agregar información adicional puede afectar tu tasa de conversión. Puedes poner el texto en negrita o insertar un enlace mediante [la sintaxis de Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Para adaptar mejor el proceso de compra 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"
```

## Localización e idiomas admitidos

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 si pasas 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 monedas. Por ejemplo, al vender un producto cuyo precio se establece 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 €.

### 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 de soporte, en Checkout. Ve a [Configuración de Checkout](https://dashboard.stripe.com/settings/checkout) para configurar la información que quieres mostrar, lo que incluye:

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

Exponer 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 [Configuración de Checkout](https://dashboard.stripe.com/settings/checkout), agrega información de contacto de soporte a tus sesiones habilitando **Información de contacto**. Del mismo modo, agrega enlaces a tus **Condiciones de uso** y **Política de privacidad** en tus sesiones habilitando **Políticas legales**. Si requieres que los clientes den su consentimiento implícito a tus políticas legales cuando completen el proceso de compra, selecciona la casilla **Mostrar acuerdo con las condiciones legales**.

Debes agregar tu información de contacto de soporte y los enlaces a la política legal en tu [Configuración de datos públicos](https://dashboard.stripe.com/settings/public).

En las siguientes vistas previas se muestra 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 de confirmación de compra con información de contacto.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

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

Vista previa de las políticas legales en Checkout.

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

Muestra tus políticas de devoluciones, reembolsos o cambios habilitando **Políticas de devoluciones y reembolsos**. Mientras que las empresas que venden productos físicos utilizan políticas de devoluciones, las empresas que venden productos digitales o bienes físicos personalizados suelen utilizar políticas de reembolso. Como no son mutuamente excluyentes, puedes seleccionar ambas opciones si tu empresa vende ambas categorías de productos. Puedes editar los detalles de la devolución y el rembolso, 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 devolver los clientes los artículos que se les enviaron
- Si aceptas devoluciones en la tienda
- Un enlace al texto completo de la política de reembolso y devoluciones
- Un mensaje personalizado

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

En las siguientes vistas previas se muestra 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 el cambio del producto) por un plazo máximo de 60 días. Puedes mostrar información similar para los reembolsos.
![Vista previa de las políticas de devoluciones en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

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

Vista previa de una política destacada en Checkout.

#### Obtén el acuerdo de condiciones de uso

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

Obtén el acuerdo de condiciones de uso

Puedes obtener un acuerdo sobre las condiciones de uso 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 obtener el acuerdo de condiciones de uso 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 uso. Antes de solicitar la aceptación de las condiciones, establece la URL de las condiciones de uso en los [datos públicos](https://dashboard.stripe.com/settings/public) de tu empresa. Establecer una URL de política de privacidad es opcional. Checkout también vincula tu política de privacidad cuando se establece una URL en tus [datos públicos](https://dashboard.stripe.com/settings/public).

Después de que un cliente completa el proceso de compra, puedes verificar que el cliente aceptó tus condiciones de uso observando el objeto Session en el webhook `checkout.session.completed` o recuperando la sesión con 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 establecer`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 a este texto. No puedes usar esta funcionalidad 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 con 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 método de pago, el contrato de reutilización 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` configurado, 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 seleccionado. 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:

- Un enlace a tus condiciones de suscripción
- Un enlace a tu portal de clientes
- Mecanismos y políticas de cancelación
![Visualización del acuerdo de reutilización del método de pago predeterminado 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 del método 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 actualizarlo a medida que cambien las normas de la red de tarjetas y la normativa local. No utilices esta funcionalidad sin consultar a tu equipo legal o configurar un texto personalizado que incluya información sobre la reutilización del método de pago. Asegúrate de que tu texto personalizado cubra todos los modos que planeas admitir.

Para ocultar el texto del acuerdo de reutilización del método de pago, configura `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout no mostrará el idioma predeterminado que rige la reutilización del método de pago. Para configurar tu propio texto en lugar del idioma predeterminado de Stripe, configura `custom_text.after_submit.message`. También puedes utilizar `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.

> Se prohíbe el uso de esta funcionalidad para crear texto personalizado que infrinja o cree ambigüedad con el texto generado por Stripe en Checkout, las obligaciones en virtud de tu contrato con Stripe, las políticas de Stripe y la legislación aplicable.

```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 la dirección de envío
![Texto personalizado arriba del botón de pago](https://b.stripecdn.com/docs-statics-srv/assets/submit-custom-text.bf46135c06b7c33c1ce9c9b09e4206c9.png)

Texto personalizado arriba del botón **Pagar**
![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 **Pagar**

El texto personalizado puede tener una longitud máxima de 1200 caracteres. Sin embargo, Stripe Checkout está optimizado para la conversión, y agregar información adicional puede afectar tu tasa de conversión. Puedes poner el texto en negrita o insertar un enlace mediante [la sintaxis de Markdown](https://www.markdownguide.org/cheat-sheet/).

### Customize the Submit button 

Para adaptar mejor el proceso de compra 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"
```

## Localización e idiomas admitidos

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 si pasas 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 monedas. Por ejemplo, al vender un producto cuyo precio se establece 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 €.

### 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 de soporte, en Checkout. Ve a [Configuración de Checkout](https://dashboard.stripe.com/settings/checkout) para configurar la información que quieres mostrar, lo que incluye:

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

Exponer 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 [Configuración de Checkout](https://dashboard.stripe.com/settings/checkout), agrega información de contacto de soporte a tus sesiones habilitando **Información de contacto**. Del mismo modo, agrega enlaces a tus **Condiciones de uso** y **Política de privacidad** en tus sesiones habilitando **Políticas legales**. Si requieres que los clientes den su consentimiento implícito a tus políticas legales cuando completen el proceso de compra, selecciona la casilla **Mostrar acuerdo con las condiciones legales**.

Debes agregar tu información de contacto de soporte y los enlaces a la política legal en tu [Configuración de datos públicos](https://dashboard.stripe.com/settings/public).

En las siguientes vistas previas se muestra 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 de confirmación de compra con información de contacto.](https://b.stripecdn.com/docs-statics-srv/assets/contact-modal.2b81bc2e74657f7c94a45a743439c81f.png)

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

Vista previa de las políticas legales en Checkout.

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

Muestra tus políticas de devoluciones, reembolsos o cambios habilitando **Políticas de devoluciones y reembolsos**. Mientras que las empresas que venden productos físicos utilizan políticas de devoluciones, las empresas que venden productos digitales o bienes físicos personalizados suelen utilizar políticas de reembolso. Como no son mutuamente excluyentes, puedes seleccionar ambas opciones si tu empresa vende ambas categorías de productos. Puedes editar los detalles de la devolución y el rembolso, 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 devolver los clientes los artículos que se les enviaron
- Si aceptas devoluciones en la tienda
- Un enlace al texto completo de la política de reembolso y devoluciones
- Un mensaje personalizado

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

En las siguientes vistas previas se muestra 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 el cambio del producto) por un plazo máximo de 60 días. Puedes mostrar información similar para los reembolsos.
![Vista previa de las políticas de devoluciones en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/return-policy-modal.0c7a9ff71b8bc2c155842532801e06a8.png)

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

Vista previa de una política destacada en Checkout.

#### Obtén el acuerdo de condiciones de uso

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

Obtén el acuerdo de condiciones de uso

Puedes obtener un acuerdo sobre las condiciones de uso 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 obtener el acuerdo de condiciones de uso 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 uso. Antes de solicitar la aceptación de las condiciones, establece la URL de las condiciones de uso en los [datos públicos](https://dashboard.stripe.com/settings/public) de tu empresa. Establecer una URL de política de privacidad es opcional. Checkout también vincula tu política de privacidad cuando se establece una URL en tus [datos públicos](https://dashboard.stripe.com/settings/public).

Después de que un cliente completa el proceso de compra, puedes verificar que el cliente aceptó tus condiciones de uso observando el objeto Session en el webhook `checkout.session.completed` o recuperando la sesión con 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 establecer`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 a este texto. No puedes usar esta funcionalidad 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 con 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 método de pago, el contrato de reutilización 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` configurado, 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 seleccionado. 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:

- Un enlace a tus condiciones de suscripción
- Un enlace a tu portal de clientes
- Mecanismos y políticas de cancelación
![Visualización del acuerdo de reutilización del método de pago predeterminado 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 del método 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 actualizarlo a medida que cambien las normas de la red de tarjetas y la normativa local. No utilices esta funcionalidad sin consultar a tu equipo legal o configurar un texto personalizado que incluya información sobre la reutilización del método de pago. Asegúrate de que tu texto personalizado cubra todos los modos que planeas admitir.

Para ocultar el texto del acuerdo de reutilización del método de pago, configura `consent_collection.payment_method_reuse_agreement.position='hidden'`. Checkout no mostrará el idioma predeterminado que rige la reutilización del método de pago. Para configurar tu propio texto en lugar del idioma predeterminado de Stripe, configura `custom_text.after_submit.message`. También puedes utilizar `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.