Skip to main content

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.

​
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.
ScenariopayMethodTypepayMethodNamepayMethodCountryNotes
User selects in cashier (recommended)OmitOmitOmitShow all available payment methods; user chooses
Card payments"CREDITCARD,DEBITCARD"OmitOmitSupports both credit and debit cards; Waffo auto-detects card network (Visa/Mastercard) from BIN, reducing user friction
Credit card only"CREDITCARD"OmitOmitShow credit cards only
VA (Virtual Account)"VA"OmitPass if neededUser selects the specific bank in the cashier
Specific walletCorresponding typeCorresponding namePass if needede.g. "EWALLET" + "DANA"

​
Examples

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

​
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": "en-HK"
  }
}
Supported languages and their applicable currencies/countries:
Language codeLanguageApplicable currencyApplicable country
enEnglishAll currenciesAll countries (default fallback)
id-IDIndonesianIDRIndonesia
vi-VNVietnameseVNDVietnam
pt-BRPortuguese (Brazil)BRLBrazil
es-MXSpanish (Mexico)MXNMexico
es-PESpanish (Peru)PENPeru
es-COSpanish (Colombia)COPColombia
es-CLSpanish (Chile)CLPChile
ru-RURussianRUBRussia
en-KEEnglish (Kenya)KESKenya
zh-Hant-TWTraditional Chinese (Taiwan)TWDTaiwan
zh-Hant-HKTraditional Chinese (Hong Kong)HKDHong Kong

​
Auto-selection logic

When cashierLanguage is not specified, Waffo selects the language automatically using the following priority:
  1. Match by user country (e.g. user country is IDN → id-ID)
  2. Match by order currency (e.g. currency is BRL → pt-BR)
  3. 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

MethodPriorityDescription
API parameter (per transaction)HighestPass via paymentInfo.cashierAppearance; can differ per transaction
Merchant Portal (global)MediumConfigure a global default theme in the Merchant Portal
SDK initialization (client-side)LowestPass 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

VariableDescriptionExample value
colorPrimaryPrimary color (buttons, links, selected state)#0570de
colorBackgroundPage background color#ffffff
colorTextMain text color#30313d
borderRadiusCorner radius8px
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 the Merchant Portal and set a global default theme on the cashier configuration page. This is the best option when all transactions should share a unified brand style.

​
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.

​
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

ParameterDescription
successRedirectUrlRedirect after a successful payment
failedRedirectUrlRedirect after a failed payment
cancelRedirectUrlRedirect 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.