Cashier integration - Customization options

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

Customization capabilities overview

Capability	API parameter	Merchant Portal	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 > Merchant Portal > SDK initialization When the same capability is configured through multiple methods, the higher-priority setting takes effect.

Payment method filtering

Use payMethodType and payMethodName to control which payment methods are displayed in the cashier. For payment method exceptions and App WebView / iframe limitations, see Payment method integration notes.

Recommended parameter combinations

Scenario	payMethodType	payMethodName	payMethodCountry	Notes
User selects in cashier (recommended)	Omit	Omit	Omit	The user enters the Waffo payment-method selection page and chooses from all available payment methods
Card payments	`"CREDITCARD,DEBITCARD"`	Omit	Omit	Supports both credit and debit cards; Waffo auto-detects card network (Visa/Mastercard) from BIN, reducing user friction
Credit card only	`"CREDITCARD"`	Omit	Omit	Show credit cards only
VA (Virtual Account)	`"VA"`	Omit	Pass if needed	User selects the specific bank in the cashier
Specific wallet	Corresponding type	Corresponding name	Pass if needed	e.g. `"EWALLET"` + `"DANA"`

Examples

// Best practice: card payments (credit + debit, Visa + Mastercard)
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "CREDITCARD,DEBITCARD"
  }
}

// VA payment (user selects bank in cashier)
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "VA"
  }
}

// Specify a particular wallet
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "EWALLET",
    "payMethodName": "DANA"
  }
}

// Omit all: user sees every available payment method
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT"
  }
}

When to pass payMethodCountry

Pass this field when you want the cashier to show payment methods for a specific country only.

Omitted: The cashier shows all payment methods available under the merchant contract across all countries.
Passed: The cashier shows only the payment methods for that country.

// Show Indonesian payment methods only
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodCountry": "IDN"
  }
}

Do not pass payMethodCountry for global card methods (CREDITCARD/DEBITCARD). Global cards do not belong to any country.

Multi-currency support

When the merchant pricing currency differs from the user payment currency (cross-currency order):

{
  "orderCurrency": "USD",
  "orderAmount": "10.00"
}

userCurrency can be omitted — Waffo automatically handles FX conversion. The user sees the amount in their local currency in the cashier.

Language settings

Use paymentInfo.cashierLanguage to set the cashier display language (IETF BCP 47 format):

{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "cashierLanguage": "id-ID"
  }
}

Supported languages and their applicable currencies/countries:

Language code	Language	Applicable currency	Applicable country
`en`	English	All currencies	All countries (default fallback)
`id-ID`	Indonesian	`IDR`	Indonesia
`vi-VN`	Vietnamese	`VND`	Vietnam
`pt-BR`	Portuguese (Brazil)	`BRL`	Brazil
`es-MX`	Spanish (Mexico)	`MXN`	Mexico
`es-PE`	Spanish (Peru)	`PEN`	Peru
`es-CO`	Spanish (Colombia)	`COP`	Colombia
`es-CL`	Spanish (Chile)	`CLP`	Chile
`ru-RU`	Russian	`RUB`	Russia
`en-KE`	English (Kenya)	`KES`	Kenya
`zh-Hant-TW`	Traditional Chinese (Taiwan)	`TWD`	Taiwan
`zh-Hant-HK`	Traditional Chinese (Hong Kong)	`HKD`	Hong Kong

Auto-selection logic

When cashierLanguage is not specified, Waffo selects the language automatically using the following priority:

Match by user country (e.g. user country is IDN → id-ID)
Match by order currency (e.g. currency is BRL → pt-BR)
No match found → fall back to en

Notes

The language must match the currency/country. For example, an order with IDR currency can only use id-ID or en; specifying pt-BR returns error code A0026.
en is the universal language and works with all currencies and countries.
Currencies not listed in the table above (e.g. USD, EUR, SGD) are only supported with en.

Unsupported languages return error code A0026.

Theme customization

Customize the cashier’s colors, fonts, and styles to match your brand.

Three configuration methods

Method	Priority	Description
API parameter (per transaction)	Highest	Pass via `paymentInfo.cashierAppearance`; can differ per transaction
Merchant Portal (global)	Medium	Configure a global default theme in the Merchant Portal
SDK initialization (client-side)	Lowest	Pass theme config when initializing the frontend SDK

Priority order: API parameter > Merchant Portal > SDK initialization. When cashierAppearance is passed via API it overrides all other settings.

Theme variables

Variable	Description	Example value
`colorPrimary`	Primary color (buttons, links, selected state)	`#0570de`
`colorBackground`	Page background color	`#ffffff`
`colorText`	Main text color	`#30313d`
`borderRadius`	Corner radius	`8px`

These variables are injected into the cashier UI rendering layer and override the default theme. They affect the payment method selection page, card form page, transition page, and payment result page.

API parameter method

Supported endpoints:

POST /api/v1/order/create
POST /api/v1/subscription/create

The cashierAppearance field must be a JSON string (not a JSON object), with the structure {"variables": { ... }}. Escape the inner quotes accordingly.

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

Merchant Portal configuration

Log in to Merchant Portal → Checkout → Cashier Customization to set a global default cashier style. Use this option when all transactions should share a unified brand style. Portal supports merchant Logo, preset themes, theme colors, base font size, and corner radius. You can preview the cashier on the right side of the page. After you click Save & Publish, the configuration applies to newly created orders.

Merchant Portal Cashier Customization page overview

If your account has sub-merchants (SubMIDs), you can either let all SubMIDs inherit the main merchant configuration or configure a separate style for each SubMID. For complete steps, see Merchant Portal cashier customization.

SDK initialization

Pass theme configuration when initializing the frontend SDK (@waffo/payment-sdk). This has the lowest priority and takes effect only when neither the API nor the Merchant Portal has a theme configured.

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

API parameter examples

Using an external URL:

{
  "brandInfo": {
    "cashierLogoUrl": "https://merchant.com/logo.png"
  }
}

Using a logo uploaded via the Portal:

{
  "brandInfo": {
    "cashierLogoUrl": "logo_abc123"
  }
}

Order expiration time

Use orderExpiredAt to set the order expiration time (ISO 8601, UTC+0).

{
  "orderExpiredAt": "2026-03-25T11:00:00.000Z"
}

This field controls the time window during which the user can submit the order in the cashier. Once the order is submitted to the payment channel, the expiration time is governed by the payment method itself. A small number of payment methods support passing a channel-side expiration time from the merchant. Check the Payin page in the Portal for expiration details per payment method.

Redirect URLs

Parameter	Description
`successRedirectUrl`	Redirect after a successful payment
`failedRedirectUrl`	Redirect after a failed payment
`cancelRedirectUrl`	Redirect after the user actively cancels

Both HTTPS URLs and deeplinks (e.g. for in-app scenarios) are supported.

Redirect URLs control the user experience only and do not represent the payment result. Always rely on Webhooks or the query API for the authoritative payment outcome.

Getting Started

Core Concepts

Integration

Webhook

SDK

Tools & Reference

Cashier integration - Customization options

Customization capabilities overview

Payment method filtering

Recommended parameter combinations

Examples

When to pass payMethodCountry

Multi-currency support

Language settings

Auto-selection logic

Notes

Theme customization

Three configuration methods

Theme variables

API parameter method

Merchant Portal configuration

SDK initialization

Merchant logo

API parameter examples

Order expiration time

Redirect URLs

​Customization capabilities overview

​Payment method filtering

​Recommended parameter combinations

​Examples

​When to pass payMethodCountry

​Multi-currency support

​Language settings

​Auto-selection logic

​Notes

​Theme customization

​Three configuration methods

​Theme variables

​API parameter method

​Merchant Portal configuration

​SDK initialization

​Merchant logo

​API parameter examples

​Order expiration time

​Redirect URLs

Customization capabilities overview

Payment method filtering

Recommended parameter combinations

Examples

When to pass payMethodCountry

Multi-currency support

Language settings

Auto-selection logic

Notes

Theme customization

Three configuration methods

Theme variables

API parameter method

Merchant Portal configuration

SDK initialization

Merchant logo

API parameter examples

Order expiration time

Redirect URLs