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.
Waffo 收银台支持多种定制化能力，商户可以通过三种方式配置外观和行为。
定制化能力概览
| 能力 | API 传参 | Portal 配置 | SDK 初始化 |
|---|
| 主题色 | 支持 | 支持 | 支持 |
| 背景色 | 支持 | 支持 | 支持 |
| 文字色 | 支持 | 支持 | 支持 |
| 圆角 | 支持 | 支持 | 支持 |
| 商户 Logo | 支持 | 支持 | - |
| 语言 | 支持 | - | 支持 |
主题样式
通过 cashierAppearance 字段配置收银台主题，支持 4 个变量：
| 变量 | 说明 | 示例 |
|---|
colorPrimary | 主题色（按钮、链接等） | "#0570de" |
colorBackground | 背景色 | "#ffffff" |
colorText | 文字色 | "#30313d" |
borderRadius | 圆角半径 | "8px" |
方式一：API 传参（每笔交易独立配置）
cashierAppearance 是 String 类型字段，值为一个 JSON 字符串。内部引号必须转义。
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"cashierAppearance": "{\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\",\"borderRadius\":\"8px\"}}"
}
}
方式二：Portal 配置（全局默认）
在 Merchant Portal 的收银台定制页面配置默认主题。所有交易默认使用此配置，除非 API 传参覆盖。
方式三：SDK 初始化（客户端默认）
在 SDK 初始化时传入主题配置：
const waffo = new WaffoSDK({
env: 'production',
appearance: {
variables: {
colorPrimary: '#0570de',
colorBackground: '#ffffff',
colorText: '#30313d',
borderRadius: '8px'
}
}
});
商户 Logo
通过 brandInfo.cashierLogoUrl 传递商户 Logo，在收银台页面展示品牌标识。
两种传递方式：
| 方式 | 格式 | 说明 |
|---|
| 外部 URL | https:// 开头 | 商户自行托管，推荐尺寸 40x40 px |
| Portal 预创建 ID | logo_ 开头 | 通过 Merchant Portal 上传后获取 |
API 传参示例
使用外部 URL：
{
"brandInfo": {
"cashierLogoUrl": "https://merchant.com/logo.png"
}
}
{
"brandInfo": {
"cashierLogoUrl": "logo_abc123"
}
}
语言设置
通过 paymentInfo.cashierLanguage 设置收银台语言，格式为 IETF BCP 47。
支持的语言
| 语言代码 | 语言 | 适用币种 | 适用国家 |
|---|
en | English | 所有 | 所有 |
id-ID | Bahasa Indonesia | IDR | 印尼 |
vi-VN | Tiếng Việt | VND | 越南 |
pt-BR | Português | BRL | 巴西 |
es-MX | Español (México) | MXN | 墨西哥 |
es-PE | Español (Perú) | PEN | 秘鲁 |
es-CO | Español (Colombia) | COP | 哥伦比亚 |
es-CL | Español (Chile) | CLP | 智利 |
ru-RU | Русский | RUB | 俄罗斯 |
en-KE | English (Kenya) | KES | 肯尼亚 |
zh-Hant-TW | 繁體中文 (台灣) | TWD | 台湾 |
zh-Hant-HK | 繁體中文 (香港) | HKD | 香港 |
自动选择逻辑
不传 cashierLanguage 时，Waffo 按以下优先级自动选择：
- 匹配用户所在国家
- 匹配订单币种对应的语言
- 兜底使用
en
语言必须与币种/国家匹配。如果传了不匹配的组合，API 会返回错误码 A0026。
传参示例
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"cashierLanguage": "id-ID"
}
}
支付方式过滤
控制收银台展示哪些支付方式。
推荐：不传 payMethodType 和 payMethodName，让收银台自动展示所有可用方式。
按需过滤：
| 场景 | 传参方式 | 说明 |
|---|
| 展示所有支付方式 | 不传 | 推荐，覆盖面最广 |
| 仅展示卡支付 | payMethodType: "CREDITCARD,DEBITCARD" | Waffo 通过 BIN 自动识别卡类型 |
| 仅展示 VA | payMethodType: "VA" | 用户在收银台选择具体银行 |
| 指定具体钱包 | payMethodType + payMethodName | 如 "EWALLET" + "DANA" |
payMethodCountry 使用指南
payMethodCountry 用于限制展示特定国家的支付方式。
不要对全球卡（CREDITCARD/DEBITCARD）传 payMethodCountry，因为信用卡和借记卡不属于任何特定国家。仅在需要限定本地支付方式时使用。
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"payMethodCountry": "IDN"
}
}
