收银台集成 - 自定义选项

Waffo 收银台支持多种定制化能力，商户可以通过三种方式配置外观和行为。

定制化能力概览

能力	API 传参	商户后台	SDK 传入
主题色	支持	支持	支持
背景色	支持	支持	支持
文字色	支持	支持	支持
圆角	支持	支持	支持
商户 Logo	支持	支持	-
语言	支持	-	支持

优先级：API 传参 > 商户后台 > SDK 传入同一能力通过多种方式配置时，高优先级的生效。

支付方式过滤

通过 payMethodType 和 payMethodName 控制收银台展示的支付方式。支付方式特例以及 App WebView / iframe 相关限制，参见支付方式集成注意事项。

场景	payMethodType	payMethodName	payMethodCountry	说明
用户在收银台选择（推荐）	不传	不传	不传	进入 Waffo 收银台的支付方式选择页，展示所有可用支付方式，由用户自选
卡类支付	`"CREDITCARD,DEBITCARD"`	不传	不传	同时支持信用卡和借记卡，Waffo 根据卡 BIN 自动识别卡组（Visa/Mastercard），减少用户决策成本
仅信用卡	`"CREDITCARD"`	不传	不传	仅展示信用卡
VA（虚拟账户）	`"VA"`	不传	按需传	用户到收银台选择具体银行
指定具体钱包	对应类型	对应名称	按需传	如 `"EWALLET"` + `"DANA"`

示例

// 最佳实践：卡类支付（同时支持信用卡+借记卡，Visa+Mastercard）
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "CREDITCARD,DEBITCARD"
  }
}

// VA 支付（用户到收银台选择银行）
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "VA"
  }
}

// 指定具体钱包
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "EWALLET",
    "payMethodName": "DANA"
  }
}

// 全部不传：用户在收银台看到所有可用支付方式
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT"
  }
}

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": "id-ID"
  }
}

常用的语言标签包括：

语言代码	语言
`en`	英语
`id-ID`	印尼语
`vi-VN`	越南语
`pt-BR`	葡萄牙语（巴西）
`es-MX`	西班牙语（墨西哥）
`es-PE`	西班牙语（秘鲁）
`es-CO`	西班牙语（哥伦比亚）
`es-CL`	西班牙语（智利）
`ru-RU`	俄语
`en-KE`	英语（肯尼亚）
`zh-Hant-TW`	繁体中文（台湾）
`zh-Hant-HK`	繁体中文（香港）
`th-TH`	泰语
`ja-JP`	日语
`en-NG`	英语（尼日利亚）
`ko-KR`	韩语
`en-HK`	英语（香港）
`zh-Hans-HK`	简体中文（香港）
`pl-PL`	波兰语
`tr-TR`	土耳其语
`zh-Hans`	简体中文
`ms-MY`	马来语

cashierLanguage 与订单币种、用户国家或地区相互独立。Waffo 会将有效的语言标签规范为标准 BCP 47 大小写格式，例如将 en-us 规范为 en-US。

自动选择逻辑

不指定 cashierLanguage 时，Waffo 按以下优先级自动选择语言：

使用浏览器 Accept-Language 请求头中优先级最高且受支持的语言
如果用户选择了非 GLB 的国家或地区标签页，使用该国家或地区对应的语言
否则，使用用户 IP 所在国家或地区对应的语言
无法匹配时，回退到 en

Waffo 只检查 Accept-Language 中 q 权重最高的语言项。如果该语言不受支持，Waffo 会继续按国家或地区选择语言。浏览器语言匹配按主语言子标签处理：en、es、id、ja、ko、ms、pl、pt、th、tr、vi 直接匹配；任意 zh-* 匹配为 zh。其他主语言不会通过浏览器语言锁定，即使该语言可通过 cashierLanguage 显式指定。通过 cashierLanguage 指定的语言，以及通过 Accept-Language 匹配的语言，都会在收银台会话中保持不变。通过国家或地区匹配的语言会随用户切换标签页而变化。GLB 没有对应语言，Waffo 会改用剩余条件判断语言。国家或地区回退使用以下映射：

国家或地区	语言
`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`

注意事项

订单币种和用户支付币种不参与收银台语言选择
cashierLanguage 会校验语言前缀和书写体系是否受支持；地区只校验是否为合法 ISO 3166-1 alpha-2 国家或地区码
不支持的语言或书写体系会返回错误码 A0026
不符合 IETF BCP 47 格式的语言标签会返回错误码 A0047

如果你希望收银台始终使用固定语言，请显式传入 paymentInfo.cashierLanguage。

主题定制

自定义收银台的颜色、字体和样式，匹配商户品牌形象。

三种配置方式

方式	优先级	说明
API 传参（按交易）	最高	在 `paymentInfo.cashierAppearance` 中传入，每笔交易可不同
商户后台（全局）	中	在 Merchant Portal 配置全局默认主题
SDK 传入（客户端）	最低	初始化前端 SDK 时传入

优先级：API 传参 > 商户后台 > SDK 传入。API 传了 cashierAppearance 会覆盖所有其他设置。

主题变量

变量名	说明	示例值
`colorPrimary`	主色调（按钮、链接、选中状态）	`#0570de`
`colorBackground`	页面背景色	`#ffffff`
`colorText`	主要文字颜色	`#30313d`
`borderRadius`	圆角大小	`8px`

这些变量会注入到收银台 UI 渲染层，覆盖默认主题。影响范围包括：支付方式选择页、卡片表单页、过渡页、支付结果页。

API 传参方式

支持的接口：

POST /api/v1/order/create
POST /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 → Checkout → Cashier Customization，在收银台客制化页面设置全局默认样式。适合所有交易使用统一品牌样式的场景。 Portal 支持配置商户 Logo、预设主题、主题颜色、字体大小和圆角，并可在页面右侧实时预览效果。点击 Save & Publish 后，配置会应用到后续新创建的订单。

如果你的账户下有子商户（SubMID），可以选择让所有子商户继承主商户配置，也可以为单个子商户设置独立样式。完整操作步骤见 Merchant Portal 收银台客制化配置。

SDK 传入

初始化前端 SDK（@waffo/payment-sdk）时传入主题配置。优先级最低，当 API 和后台都未配置时生效。

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 传参示例

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

使用 Portal 上传的 Logo：

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

订单过期时间

通过 orderExpiredAt 设置订单过期时间（ISO 8601，UTC+0）。

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

该字段控制的是用户在收银台提交订单的时间窗口。一旦订单提交到支付渠道后，过期时间由支付方式自身控制，极少数支付方式支持商户传入渠道侧过期时间。具体可登录 Portal，到 Payin 页面查看各支付方式的过期时间说明。

重定向 URL

参数	说明
`successRedirectUrl`	支付成功后重定向
`failedRedirectUrl`	支付失败后重定向
`cancelRedirectUrl`	用户主动取消后重定向

支持 HTTPS 链接和 deeplink 链接（如 App 场景）。

重定向仅控制用户体验，不代表支付结果。始终以 Webhook 或查询接口为准。

快速开始

核心概念

集成

Webhook

SDK

工具与参考

点卡充值 API

收银台集成 - 自定义选项

定制化能力概览

支付方式过滤

推荐传参方式

示例

payMethodCountry 什么时候需要传

多币种支持

语言设置

自动选择逻辑

注意事项

主题定制

三种配置方式

主题变量

API 传参方式

商户后台配置

SDK 传入

商户 Logo

API 传参示例

订单过期时间

重定向 URL

​定制化能力概览

​支付方式过滤

​推荐传参方式

​示例

​payMethodCountry 什么时候需要传

​多币种支持

​语言设置

​自动选择逻辑

​注意事项

​主题定制

​三种配置方式

​主题变量

​API 传参方式

​商户后台配置

​SDK 传入

​商户 Logo

​API 传参示例

​订单过期时间

​重定向 URL

定制化能力概览

支付方式过滤

推荐传参方式

示例

payMethodCountry 什么时候需要传

多币种支持

语言设置

自动选择逻辑

注意事项

主题定制

三种配置方式

主题变量

API 传参方式

商户后台配置

SDK 传入

商户 Logo

API 传参示例

订单过期时间

重定向 URL