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.
支付方式过滤
通过 payMethodType 和 payMethodName 控制收银台展示的支付方式。
支付方式特例以及 App WebView / iframe 相关限制，参见 支付方式集成注意事项。
推荐传参方式
| 场景 | payMethodType | payMethodName | payMethodCountry | 说明 |
|---|
| 用户在收银台选择（推荐） | 不传 | 不传 | 不传 | 展示所有可用支付方式，用户自选 |
| 卡类支付 | "CREDITCARD,DEBITCARD" | 不传 | 不传 | 同时支持信用卡和借记卡，Waffo 根据卡 BIN 自动识别卡组（Visa/Mastercard），减少用户决策成本 |
| 仅信用卡 | "CREDITCARD" | 不传 | 不传 | 仅展示信用卡 |
| VA（虚拟账户） | "VA" | 不传 | 按需传 | 用户到收银台选择具体银行 |
| 指定具体钱包 | 对应类型 | 对应名称 | 按需传 | 如 "EWALLET" + "DANA" |
// 最佳实践：卡类支付（同时支持信用卡+借记卡，Visa+Mastercard）
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"payMethodType": "CREDITCARD,DEBITCARD"
}
}
payMethodCountry 什么时候需要传
当商户希望收银台只展示指定国家的支付方式时传入。
- 不传：收银台展示商户合约下所有国家的可用支付方式
- 传入：收银台仅展示该国家的支付方式
// 仅展示印尼的支付方式
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"payMethodCountry": "IDN"
}
}
全球卡（CREDITCARD/DEBITCARD）不要传 payMethodCountry，全球卡不属于任何国家。
多币种支持
当商户定价币种与用户支付币种不同时（跨币种下单）：
{
"orderCurrency": "USD",
"orderAmount": "10.00"
}
userCurrency 可不传，Waffo 自动处理汇率换算。用户在收银台看到的是当地货币金额。
语言设置
通过 paymentInfo.cashierLanguage 设置收银台显示语言（IETF BCP 47 格式）：
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"cashierLanguage": "en-HK"
}
}
| 语言代码 | 语言 | 适用币种 | 适用国家 |
|---|
en | English | 所有币种 | 所有国家（默认回退语言） |
id-ID | 印尼语 | IDR | 印度尼西亚 |
vi-VN | 越南语 | VND | 越南 |
pt-BR | 葡萄牙语（巴西） | BRL | 巴西 |
es-MX | 西班牙语（墨西哥） | MXN | 墨西哥 |
es-PE | 西班牙语（秘鲁） | PEN | 秘鲁 |
es-CO | 西班牙语（哥伦比亚） | COP | 哥伦比亚 |
es-CL | 西班牙语（智利） | CLP | 智利 |
ru-RU | 俄语 | RUB | 俄罗斯 |
en-KE | 英语（肯尼亚） | KES | 肯尼亚 |
zh-Hant-TW | 繁体中文（台湾） | TWD | 台湾 |
zh-Hant-HK | 繁体中文（香港） | HKD | 香港 |
自动选择逻辑
不指定 cashierLanguage 时，Waffo 按以下优先级自动选择语言：
- 根据用户国家匹配（如用户国家为 IDN →
id-ID）
- 根据订单币种匹配（如币种为 BRL →
pt-BR）
- 以上均无匹配 → 回退到
en
注意事项
- 语言必须与币种/国家匹配。例如
IDR 币种的订单只能指定 id-ID 或 en，指定 pt-BR 会返回错误码 A0026
en 是通用语言，适用于所有币种和国家- 未在上表中列出的币种（如
USD、EUR、SGD 等），收银台仅支持 en
主题定制
自定义收银台的颜色、字体和样式，匹配商户品牌形象。
三种配置方式
| 方式 | 优先级 | 说明 |
|---|
| API 传参（按交易） | 最高 | 在 paymentInfo.cashierAppearance 中传入，每笔交易可不同 |
| 商户后台（全局） | 中 | 在 Merchant Portal 配置全局默认主题 |
| SDK 传入（客户端） | 最低 | 初始化前端 SDK 时传入 |
cashierAppearance 会覆盖所有其他设置。
主题变量
| 变量名 | 说明 | 示例值 |
|---|
colorPrimary | 主色调（按钮、链接、选中状态） | #0570de |
colorBackground | 页面背景色 | #ffffff |
colorText | 主要文字颜色 | #30313d |
borderRadius | 圆角大小 | 8px |
API 传参方式
支持的接口：
POST /api/v1/order/createPOST /api/v1/subscription/create
cashierAppearance 字段必须是 JSON 字符串（不是 JSON 对象），结构为 {"variables": { ... }}，需要对内部的引号做转义。
{
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"cashierAppearance": "{\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\",\"borderRadius\":\"8px\"}}"
}
}
商户后台配置
登录 Merchant Portal，在收银台配置页面设置全局默认主题。适合所有交易使用统一品牌样式的场景。
SDK 传入
初始化前端 SDK（@waffo/payment-sdk）时传入主题配置。优先级最低，当 API 和后台都未配置时生效。
订单过期时间
通过 orderExpiredAt 设置订单过期时间（ISO 8601，UTC+0）。
{
"orderExpiredAt": "2026-03-25T11:00:00.000Z"
}
重定向 URL
| 参数 | 说明 |
|---|
successRedirectUrl | 支付成功后重定向 |
failedRedirectUrl | 支付失败后重定向 |
cancelRedirectUrl | 用户主动取消后重定向 |
重定向仅控制用户体验，不代表支付结果。始终以 Webhook 或查询接口为准。
