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

Common language tags include:

Language code	Language
`en`	English
`id-ID`	Indonesian
`vi-VN`	Vietnamese
`pt-BR`	Portuguese (Brazil)
`es-MX`	Spanish (Mexico)
`es-PE`	Spanish (Peru)
`es-CO`	Spanish (Colombia)
`es-CL`	Spanish (Chile)
`ru-RU`	Russian
`en-KE`	English (Kenya)
`zh-Hant-TW`	Traditional Chinese (Taiwan)
`zh-Hant-HK`	Traditional Chinese (Hong Kong)
`th-TH`	Thai
`ja-JP`	Japanese
`en-NG`	English (Nigeria)
`ko-KR`	Korean
`en-HK`	English (Hong Kong)
`zh-Hans-HK`	Simplified Chinese (Hong Kong)
`pl-PL`	Polish
`tr-TR`	Turkish
`zh-Hans`	Simplified Chinese
`ms-MY`	Malay

cashierLanguage is independent of the order currency and the user’s country or region. Waffo normalizes valid language tags to standard BCP 47 casing, such as en-us to en-US.

Auto-selection logic

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

Use the highest-priority supported language in the browser’s Accept-Language header
If the user selects a country or region tab other than GLB, use the language mapped to that country or region
Otherwise, use the language mapped to the user’s IP country or region
If no language matches, fall back to en

Waffo checks only the language with the highest q weight in Accept-Language. If that language is unsupported, Waffo continues with country or region selection. Browser-language matching uses the primary language subtag: en, es, id, ja, ko, ms, pl, pt, th, tr, and vi match directly; any zh-* tag maps to zh. Other primary languages do not lock the cashier through browser matching, even when you can specify that language through cashierLanguage. A language specified through cashierLanguage or matched from Accept-Language remains fixed during the cashier session. A language derived from a country or region changes when the user switches tabs. GLB has no mapped language, so Waffo uses the remaining conditions to select a language. Country or region fallback uses these mappings:

Country or region	Language
`BRA`	`pt-BR`
`MEX`	`es-MX`
`IDN`	`id-ID`
`VNM`	`vi-VN`
`RUS`	`ru-RU`
`KEN`	`en-KE`
`PER`	`es-PE`
`COL`	`es-CO`
`CHL`	`es-CL`
`TWN`	`zh-Hant-TW`
`HKG`	`zh-Hant-HK`
`THA`	`th-TH`
`JPN`	`ja-JP`
`NGA`	`en-NG`
`KOR`	`ko-KR`
`POL`	`pl-PL`
`TUR`	`tr-TR`
`MYS`	`en`
`CHN`	`zh-Hans`

Notes

The order currency and user payment currency do not participate in cashier language selection.
cashierLanguage validates whether the language prefix and script are supported. The region only needs to be a valid ISO 3166-1 alpha-2 country or region code.
An unsupported language or script returns error code A0026.
A language tag that does not follow IETF BCP 47 format returns error code A0047.

To keep the cashier language fixed, explicitly pass paymentInfo.cashierLanguage.

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

Point Topup API

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