Personalizar el checkout

Plantillas, colores, fuentes, texto del botón e idioma: guardados una vez para tu negocio o definidos por sesión.

Controlas cómo se ve y cómo se lee el checkout en dos niveles: valores por defecto de tu negocio, guardados una sola vez, y valores que sobrescribes en una sesión, enviados al crearla.

La demo interactiva muestra cada opción de esta página aplicada a un checkout en vivo.

Qué puedes cambiar

Ajuste	Campo	Valores
Distribución	`ui_config.template`	`ecommerce` (por defecto), `deposit`, `subscription`
Colores, fuente, formas, logo	`ui_config`, `logo`	Ver Campos de `ui_config`
Texto del botón de pago	`submit_type`	`pay` (por defecto), `deposit`, `subscribe` — o tu propio texto en `ui_config.buttons.payment_button.text`
Idioma	`locale`	`es` (por defecto), `en`, `zh` — el cliente puede cambiarlo en la página
Diseño del checkout	`checkout_ui_version`	`v2` (por defecto en sesiones de pago), `v1`

Una plantilla solo cambia la apariencia. Nunca cambia montos, artículos, métodos de pago ni el procesamiento.

Qué valor gana

Ajuste	Orden de resolución	¿Fijo desde la creación?
`checkout_ui_version`, `submit_type`, `locale`	Valor enviado en la sesión → valor por defecto de tu negocio → valor por defecto de Tonder (`v2`, `pay`, `es`)	Sí. Los cambios posteriores a tus valores por defecto no afectan a las sesiones ya creadas.
`ui_config` (apariencia)	Valores de la sesión sobre la apariencia de tu negocio, campo por campo	No. Un cambio en la apariencia de tu negocio también aplica a las sesiones abiertas que no sobrescriben ese campo.

Los cambios en los valores por defecto del negocio pueden tardar hasta 10 minutos en aplicarse a las sesiones nuevas.

Método 1: guarda los valores por defecto de tu negocio

Envía tus valores por defecto una sola vez. Aplican a todas las sesiones, a menos que la sesión los sobrescriba. El cuerpo es un formulario (multipart/form-data), así que puedes subir un archivo de logo.

Campo	Tipo	Requerido	Valores	Descripción
`status`	string	Sí	`active`, `inactive`	Si la configuración está en uso.
`ui_config`	string (JSON)	Sí	Ver Campos de `ui_config`	Tu apariencia por defecto.
`logo`	file	No	PNG, JPG	Logo a subir. Reemplaza a `logo_url`.
`logo_url`	string	No	URL	Dirección del logo, usada cuando no se envía un archivo.
`checkout_ui_version`	string	No	`v1`, `v2`	Diseño del checkout por defecto. Envía `v1` para mantener tu negocio en el diseño de primera generación.
`submit_type`	string	No	`pay`, `deposit`, `subscribe`	Tipo de botón por defecto para las sesiones de pago.
`locale`	string	No	`es`, `en`, `zh`	Idioma del checkout por defecto.
`version`	string	No	p. ej. `V1`	Qué apariencia guardar; las sesiones la eligen con `ui_config_version`. Por defecto `V1`.

Los campos que no envías conservan su valor guardado, excepto ui_config y status, que siempre se envían.

curl -X POST 'https://api-stage.tonder.io/checkout/v1/business/config' \
  -H 'Authorization: Token YOUR_TEST_API_KEY' \
  -F 'status=active' \
  -F 'ui_config={"template":"ecommerce","branding":{"brand_color":"#025E73"},"theme":{"font_family":"inter","shapes":"rounded"}}' \
  -F 'checkout_ui_version=v2' \
  -F 'submit_type=pay' \
  -F 'locale=es' \
  -F 'logo=@logo.png'

curl -X POST 'https://api.tonder.io/checkout/v1/business/config' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -F 'status=active' \
  -F 'ui_config={"template":"ecommerce","branding":{"brand_color":"#025E73"},"theme":{"font_family":"inter","shapes":"rounded"}}' \
  -F 'checkout_ui_version=v2' \
  -F 'submit_type=pay' \
  -F 'locale=es' \
  -F 'logo=@logo.png'

Lee lo que guardaste

GET /checkout/v1/business/config devuelve tus valores por defecto guardados, o una configuración vacía si todavía no has guardado una.

{
  "status": "active",
  "ui_config": { "template": "ecommerce", "branding": { "brand_color": "#025E73" } },
  "logo_url": "https://your-store.com/assets/logo.png",
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "es"
}

También puedes editar la apariencia en el Dashboard, con una vista previa en vivo del checkout real; consulta Payment links.

Método 2: sobrescribe en una sesión

Envía ui_config, submit_type, locale o checkout_ui_version al crear la sesión. Este ejemplo usa la distribución y el botón de depósito en una sola sesión:

{
  "customer": { "first_name": "Ana", "last_name": "Garcia", "email": "ana@example.com" },
  "amount_total": 100.00,
  "currency": "MXN",
  "line_items": [{ "name": "Deposit", "quantity": 1, "unit_price": 100.00 }],
  "payment_method_types": ["card", "spei", "apple_pay"],
  "submit_type": "deposit",
  "locale": "en",
  "ui_config": {
    "template": "deposit",
    "branding": { "brand_color": "#025E73" }
  },
  "external_id": "ORD-001",
  "return_url": "https://your-store.com/checkout/complete"
}

Campos de `ui_config`

Se aceptan en ambos métodos. Los colores son códigos HEX.

Campo	Tipo	Valores	Descripción
`template`	string	`ecommerce` (por defecto), `deposit`, `subscription`	Distribución del checkout.
`branding.brand_color`, `branding.accent_color`	string	Color HEX	Colores principal y de acento.
`theme.background_color`, `theme.card_background_color`	string	Color HEX	Fondos de la página y de la tarjeta. Usa colores claros: los colores del texto del checkout no se derivan de estos valores, así que un fondo oscuro deja ilegible el resumen del pedido.
`theme.font_family`	string	`inter` (por defecto), `system`, `geist`, `georgia`, `serif`, `monospace`	Fuente del diseño `v2`. Otros valores usan la fuente por defecto.
`theme.shapes`	string	`rounded`, `rectangular`, `pill`	Estilo de las esquinas de botones y campos.
`buttons.payment_button.text`	string	—	Texto personalizado del botón de pago. Tiene precedencia sobre `submit_type`.
`buttons.payment_button.background_color`, `.text_color`	string	Color HEX	Colores del botón de pago. En el diseño `v2` el color del texto se ajusta para que sea legible.
`labels.card_number`, `.card_holder_name`, `.expiration_date`, `.cvv`	string	—	Etiquetas del formulario de tarjeta.
`placeholders.card_number`, `.card_holder_name`, `.expiration_month`, `.expiration_year`, `.cvv`	string	—	Textos de ejemplo del formulario de tarjeta.

Referencia de la API

Autorización

Authorization

Authorization<token>

Your public API key, with the word Token and a space in front of it. Example: Token 6534bc0a7e1f4d2b9c8e3a5f7b1d2c4e6f8a9b0c — that whole value is the header. Sending the key alone returns 401 'Authentication credentials were not provided'. In this playground you may paste just the key; the prefix is added for you.

In: header

Cuerpo de la petición

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

status*string

Whether the configuration is in use.

ui_config*string

Your default appearance, as a JSON string. Same fields as the ui_config object of a session.

logo?string

Logo file to upload (PNG or JPG). Replaces logo_url.

logo_url?string

Logo address, used when no file is sent.

checkout_ui_version?string

Default checkout design. Send v1 to keep your business on the first-generation design.

submit_type?string

Default button type for payment sessions.

locale?string

Default checkout language.

version?string

Which appearance to save; sessions choose it with ui_config_version. Defaults to V1. Unrelated to checkout_ui_version.

type?string

Always SESSION.

Cuerpo de la respuesta

`application/json`

curl -X POST "https://example.com/checkout/v1/business/config" \  -F status="active" \  -F ui_config="{\"template\":\"ecommerce\",\"branding\":{\"brand_color\":\"#025E73\"},\"theme\":{\"font_family\":\"inter\",\"shapes\":\"rounded\"}}"

{
  "status": "active",
  "ui_config": {
    "template": "ecommerce",
    "branding": {
      "brand_color": "#025E73"
    },
    "theme": {
      "font_family": "inter",
      "shapes": "rounded"
    }
  },
  "logo_url": "https://your-store.com/assets/logo.png",
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "es"
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {},
  "name": "TNDR004",
  "statusCode": 400
}

Personalizar el checkout

Qué puedes cambiar

Qué valor gana

Método 1: guarda los valores por defecto de tu negocio

Lee lo que guardaste

Método 2: sobrescribe en una sesión

Campos de `ui_config`

Referencia de la API

Autorización

Cuerpo de la petición

Cuerpo de la respuesta

`application/json`

`application/json`

Siguientes pasos

Demo interactiva

Crear una sesión

Embeber el checkout

Mantener el diseño v1

En esta página

Personalizar el checkout

200application/json

400application/json

Demo interactiva

Crear una sesión

Embeber el checkout

Mantener el diseño v1

En esta página

`application/json`

`application/json`