Customize the Checkout

Templates, colors, fonts, button text and language — saved once for your business or set per session.

You control how the checkout looks and reads at two levels: defaults for your business, saved once, and overrides on a session, sent when you create it.

The interactive demo shows every option on this page applied to a live checkout.

What you can change

Setting	Field	Values
Layout	`ui_config.template`	`ecommerce` (default), `deposit`, `subscription`
Colors, font, shapes, logo	`ui_config`, `logo`	See `ui_config` fields
Pay button wording	`submit_type`	`pay` (default), `deposit`, `subscribe` — or your own text in `ui_config.buttons.payment_button.text`
Language	`locale`	`es` (default), `en`, `zh` — the customer can still switch on the page
Checkout design	`checkout_ui_version`	`v2` (default for payment sessions), `v1`

A template only changes the look. It never changes amounts, items, payment methods or processing.

Which value wins

Setting	Resolution order	Fixed at creation?
`checkout_ui_version`, `submit_type`, `locale`	Value sent on the session → your business default → Tonder's default (`v2`, `pay`, `es`)	Yes. Later changes to your defaults do not affect sessions already created.
`ui_config` (appearance)	Session values on top of your business appearance, field by field	No. A change to your business appearance also applies to open sessions that do not override that field.

Changes to business defaults can take up to 10 minutes to apply to new sessions.

Method 1: save your business defaults

Send your defaults once. They apply to every session unless the session overrides them. The body is a form (multipart/form-data), so you can upload a logo file.

Field	Type	Required	Values	Description
`status`	string	Yes	`active`, `inactive`	Whether the configuration is in use.
`ui_config`	string (JSON)	Yes	See `ui_config` fields	Your default appearance.
`logo`	file	No	PNG, JPG	Logo to upload. Replaces `logo_url`.
`logo_url`	string	No	URL	Logo address, used when no file is sent.
`checkout_ui_version`	string	No	`v1`, `v2`	Default checkout design. Send `v1` to keep your business on the first-generation design.
`submit_type`	string	No	`pay`, `deposit`, `subscribe`	Default button type for payment sessions.
`locale`	string	No	`es`, `en`, `zh`	Default checkout language.
`version`	string	No	e.g. `V1`	Which appearance to save; sessions choose it with `ui_config_version`. Defaults to `V1`.

Fields you do not send keep their saved value, except ui_config and status, which are always sent.

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'

Read what you saved

GET /checkout/v1/business/config returns your saved defaults, or an empty configuration if you have not saved one yet.

{
  "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"
}

You can also edit the appearance in the Dashboard, with a live preview of the real checkout — see Payment Links.

Method 2: override on a session

Send ui_config, submit_type, locale or checkout_ui_version when you create the session. This example uses the deposit layout and button for one session:

{
  "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"
}

`ui_config` fields

Accepted in both methods. Colors are HEX codes.

Field	Type	Values	Description
`template`	string	`ecommerce` (default), `deposit`, `subscription`	Layout of the checkout.
`branding.brand_color`, `branding.accent_color`	string	HEX color	Main and accent colors.
`theme.background_color`, `theme.card_background_color`	string	HEX color	Page and card backgrounds. Use light colors: the checkout's text colors are not derived from these values, so a dark background leaves the order summary unreadable.
`theme.font_family`	string	`inter` (default), `system`, `geist`, `georgia`, `serif`, `monospace`	Font of the `v2` design. Other values use the default.
`theme.shapes`	string	`rounded`, `rectangular`, `pill`	Corner style of buttons and fields.
`buttons.payment_button.text`	string	—	Custom pay button text. Takes precedence over `submit_type`.
`buttons.payment_button.background_color`, `.text_color`	string	HEX color	Pay button colors. In the `v2` design the text color is adjusted for readability.
`labels.card_number`, `.card_holder_name`, `.expiration_date`, `.cvv`	string	—	Card form labels.
`placeholders.card_number`, `.card_holder_name`, `.expiration_month`, `.expiration_year`, `.cvv`	string	—	Card form placeholders.

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

Request Body

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.

Response Body

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

Customize the Checkout

What you can change

Which value wins

Method 1: save your business defaults

Read what you saved

Method 2: override on a session

`ui_config` fields

API reference

Authorization

Request Body

Response Body

`application/json`

`application/json`

Next steps

Interactive demo

Create a session

Embed the checkout

Staying on the v1 design

On this page

Customize the Checkout

200application/json

400application/json

Interactive demo

Create a session

Embed the checkout

Staying on the v1 design

On this page

`application/json`

`application/json`