> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout customization

> Customize the checkout appearance, logo, language, and payment methods via API parameters, Portal settings, or SDK initialization.

The Waffo checkout supports several customization options. Merchants can configure its appearance and behavior through three methods.

## Customization capabilities overview

| Capability       | API parameter | Portal setting | SDK initialization |
| ---------------- | ------------- | -------------- | ------------------ |
| Primary color    | Supported     | Supported      | Supported          |
| Background color | Supported     | Supported      | Supported          |
| Text color       | Supported     | Supported      | Supported          |
| Border radius    | Supported     | Supported      | Supported          |
| Merchant logo    | Supported     | Supported      | -                  |
| Language         | Supported     | -              | Supported          |

**Priority**: API parameter > Portal setting > SDK initialization

When the same capability is configured through multiple methods, the higher-priority setting takes effect.

## Theme styles

Use the `cashierAppearance` field to configure the checkout theme. Four variables are supported:

| Variable          | Description                          | Example     |
| ----------------- | ------------------------------------ | ----------- |
| `colorPrimary`    | Primary color (buttons, links, etc.) | `"#0570de"` |
| `colorBackground` | Background color                     | `"#ffffff"` |
| `colorText`       | Text color                           | `"#30313d"` |
| `borderRadius`    | Border radius                        | `"8px"`     |

### Method 1: API parameter (per-transaction)

<Warning>
  `cashierAppearance` is a String field whose value is a JSON string. Internal quotes must be escaped.
</Warning>

```json theme={null}
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "cashierAppearance": "{\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\",\"borderRadius\":\"8px\"}}"
  }
}
```

### Method 2: Portal setting (global default)

Configure the default theme on the checkout customization page in the [Merchant Portal](https://dashboard.waffo.com/checkout/cashier-customization). All transactions use this configuration by default unless overridden by an API parameter.

To upload a Logo, configure theme colors, set separate sub-merchant styles, or publish a configuration, see [Merchant Portal cashier customization](/en/developer-docs/integration/checkout/portal-customization).

### Method 3: SDK initialization (client-side default)

Pass the theme configuration when initializing the SDK:

```typescript theme={null}
const waffo = new WaffoSDK({
  env: 'production',
  appearance: {
    variables: {
      colorPrimary: '#0570de',
      colorBackground: '#ffffff',
      colorText: '#30313d',
      borderRadius: '8px'
    }
  }
});
```

## Merchant logo

Pass the merchant logo via `brandInfo.cashierLogoUrl` to display your brand identity on the checkout page.

Two formats are supported:

| Format                | Value                  | Notes                                                                                                              |
| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| External URL          | Starts with `https://` | Hosted by the merchant. Recommended size: 40×40 px                                                                 |
| Portal pre-created ID | Starts with `logo_`    | Obtained after uploading through the [Merchant Portal](https://dashboard.waffo.com/checkout/cashier-customization) |

### API parameter examples

Using an external URL:

```json theme={null}
{
  "brandInfo": {
    "cashierLogoUrl": "https://merchant.com/logo.png"
  }
}
```

Using a logo uploaded via the Portal:

```json theme={null}
{
  "brandInfo": {
    "cashierLogoUrl": "logo_abc123"
  }
}
```

## Language settings

Set the checkout language via `paymentInfo.cashierLanguage` using IETF BCP 47 format.

### Supported languages

| Language code | Language           | Applicable currency | Applicable country |
| ------------- | ------------------ | ------------------- | ------------------ |
| `en`          | English            | All                 | All                |
| `id-ID`       | Bahasa Indonesia   | IDR                 | Indonesia          |
| `vi-VN`       | Tiếng Việt         | VND                 | Vietnam            |
| `pt-BR`       | Português          | BRL                 | Brazil             |
| `es-MX`       | Español (México)   | MXN                 | Mexico             |
| `es-PE`       | Español (Perú)     | PEN                 | Peru               |
| `es-CO`       | Español (Colombia) | COP                 | Colombia           |
| `es-CL`       | Español (Chile)    | CLP                 | Chile              |
| `ru-RU`       | Русский            | RUB                 | Russia             |
| `en-KE`       | English (Kenya)    | KES                 | Kenya              |
| `zh-Hant-TW`  | 繁體中文 (Taiwan)      | TWD                 | Taiwan             |
| `zh-Hant-HK`  | 繁體中文 (Hong Kong)   | HKD                 | Hong Kong          |

### Automatic selection logic

When `cashierLanguage` is not provided, Waffo selects the language automatically in the following order:

1. Match the user's country
2. Match the language associated with the order currency
3. Fall back to `en`

<Note>
  The language must match the currency and country. If a mismatched combination is provided, the API returns error code `A0026`.
</Note>

### Parameter example

```json theme={null}
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "cashierLanguage": "id-ID"
  }
}
```

## Payment method filtering

Control which payment methods are displayed on the checkout page.

**Recommended**: Do not pass `payMethodType` or `payMethodName`, and let the checkout display all available methods automatically.

Filtering options:

| Scenario                 | Parameter                               | Notes                                               |
| ------------------------ | --------------------------------------- | --------------------------------------------------- |
| Show all payment methods | Not passed                              | Recommended for widest coverage                     |
| Cards only               | `payMethodType: "CREDITCARD,DEBITCARD"` | Waffo identifies card type automatically via BIN    |
| Virtual account only     | `payMethodType: "VA"`                   | User selects the specific bank on the checkout page |
| Specific wallet          | `payMethodType` + `payMethodName`       | For example `"EWALLET"` + `"DANA"`                  |

### payMethodCountry usage guide

`payMethodCountry` restricts the checkout to payment methods available in a specific country.

<Warning>
  Do not pass `payMethodCountry` for global cards (CREDITCARD/DEBITCARD), as credit and debit cards are not tied to any specific country. Use this parameter only when you need to restrict to local payment methods.
</Warning>

```json theme={null}
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodCountry": "IDN"
  }
}
```