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

# 客制化收银台页面（品牌、颜色、Logo）

> 如何为 Waffo 收银台页面做品牌定制：Customization 在 Portal 的哪里、可以设置的每个颜色和尺寸、创建订单时哪个字段控制字号、订单参数如何覆盖 Portal 设置、MID 与 SubMID 配置、多个 Logo 和 Logo ID、实时预览及其限制，以及团队中谁可以保存更改。

本页介绍 Waffo 托管收银台页面的外观——颜色、字体、Logo 和商户名称。支付方式出现的*顺序*是另一项设置，由收银台支付方式展示规则页面介绍。页面在订单生命周期中的行为（重新打开的链接、处理中状态、结果跳转）由收银台页面生命周期与收据页面介绍。

## 我在哪里配置 Waffo 收银台的外观？

在 Merchant Portal 中打开 **Checkout → Customization**。该页面有三个标签页，旁边是实时预览：

| 标签页 | 内容 |
| - | - |
| **Features** | 商户 Logo 上传和 Logo 列表 |
| **Style** | 主题和颜色、文字信息（头部布局和字号），以及——账户已开通时——金额展示 |
| **Cashier Ranking** | 支付方式的出现顺序（按国家），以及按国家分组开关 |

三个标签页上的更改都先在本地暂存，按 **Save** 时一起提交。

## 我到底能改哪些颜色和尺寸？

Style 标签页提供四个预设主题（**Default**、**Yellow**、**Dark**、**Green**）作为一键起点，然后是以下单项控件：

| 控件 | 作用范围 | 取值范围 |
| - | - | - |
| `colorPrimary` | 主色/品牌色——按钮和强调色 | 任意颜色 |
| `colorBackground` | 页面背景 | 任意颜色 |
| `colorCard` | 卡片背景 | 任意颜色 |
| `colorText` | 主要文字 | 任意颜色 |
| `colorTextSecondary` | 次要文字 | 任意颜色 |
| `colorTextTertiary` | 第三级文字 | 任意颜色 |
| `colorDanger` | 错误文字和错误状态 | 任意颜色 |
| `colorInfo` | 信息/提示区块 | 任意颜色 |
| `colorBorder` | 边框和分割线 | 任意颜色 |
| `fontSizeBase` | 页面基础字号 | 12–24 px |
| `buttonRadius` | 按钮圆角 | 0 px 及以上 |

在 **Text Information** 下，你还可以选择头部以 **Order Description** 还是 **Merchant Name** 为主，并分别设置字号（14–24 px）。

**Amount Display** 区块——哪个币种作为主金额显示，以及主/次金额字号——只对已开通的账户出现。如果你看不到它，说明你的账户未开通。

选择预设主题会替换颜色和尺寸，但保留你的 Text Information 和 Amount Display 选择。

## 我创建订单时，哪个字段控制收银台页面的字号？

`paymentInfo.cashierAppearance`。它是一个**JSON 字符串**，携带一个 `variables` 对象，基础字号就是其中的 `fontSizeBase` 键：

```json theme={null}
{
  "variables": {
    "fontSizeBase": "18px",
    "colorPrimary": "#2749F8",
    "buttonRadius": "24px",
    "headerDisplay": {
      "primaryDisplay": "orderDesc",
      "orderDescFontSize": "18px",
      "merchantNameFontSize": "14px"
    }
  }
}
```

键名与上表列出的完全一致，尺寸以字符串形式带 `px` 单位。两个值得了解的行为：

* 该值必须是**合法 JSON**。格式错误的字符串会被丢弃，订单仍会创建——它只会改用你的 Portal 配置渲染，且没有错误提示告诉你原因。
* 只有你发送的键会被应用。你省略的所有内容回退到你的 Portal 配置，再回退到系统默认值。

## 我的 Portal 样式没有出现在收银台页面上，谁优先？

样式按以下顺序解析，最高优先级在前：

| 优先级 | 来源 |
| - | - |
| 1 | 订单上发送的值（`paymentInfo.cashierAppearance`，以及下文的品牌字段） |
| 2 | 你在 Portal **Checkout → Customization** 的配置 |
| 3 | Waffo 系统默认值 |

合并是**按键**进行的，不是全有或全无：只设置了 `colorPrimary` 的 `cashierAppearance` 会保留你 Portal 中其他所有键的值。所以如果只有某一个颜色看起来不对而其余正常，先检查你的集成在订单上发了什么，再检查 Portal。

同样的优先级适用于两个品牌字段：

| 字段 | 效果 |
| - | - |
| `brandInfo.cashierDisplayName` | 覆盖该次收银会话中配置的商户展示名称。最多 128 个字符 |
| `brandInfo.cashierLogoUrl` | 覆盖该次收银会话中配置的 Logo。最多 512 个字符 |

## 我保存了新样式，它会影响哪些订单？

配置是在**收银台页面渲染时**读取的，不是在订单创建时冻结的。实际上：

* 客户已经打开的收银台页面不受影响——在重新加载之前它保持加载时的样式。
* 保存之后打开的任何收银台页面都会使用新配置，包括你保存之前创建的订单的页面。

你的 Portal 样式没有按订单的快照。如果某个特定订单必须保持特定外观，不受之后 Portal 编辑的影响，请把样式直接发送在该订单上。

## 我的每个 SubMID 可以有自己的外观吗？

可以。Customization 页面有一个 **Configuration Scope** 卡片，列出你的 SubMID，由一个开关控制：

| `Apply MID config to all SubMIDs` | 行为 |
| - | - |
| **开** | 隐藏 SubMID 列表；你只维护一份配置 |
| **关** | 每个 SubMID 列出，带状态标签和各自的操作 |

开关关闭时，每一行 SubMID 显示 **Using MID config** 或 **Customized**。**Edit** 在同样的三个标签页中打开该 SubMID——你编辑的是该 SubMID 而不是 MID，头部会告诉你这一点。**Reset**（只对已客制化的 SubMID 提供，且需要确认）会丢弃该 SubMID 自己的 Logo 和样式，使其回到 Using MID config。

两个让人意外的细节：

* 打开一个处于 **Using MID config** 的 SubMID，会显示 MID 的样式作为起点，但**不**显示 MID 的 Logo。如果你什么都不改，该 SubMID 保持 Using MID config——不会被悄悄转成客制化的。
* 只有拥有可用支付方式的 SubMID 才会被列出。

## 如何上传多个 Logo，Logo ID 从哪里来？

在 **Features** 标签页上传 Logo。页面强制执行的规则：

| 规则 | 详情 |
| - | - |
| 格式 | 仅 **PNG、JPG、JPEG**——SVG 会被拒绝 |
| 推荐尺寸 | 40 × 40 px |
| 默认 Logo | 你上传的第一个 Logo 自动成为默认；**Set as default** 可把默认移到任何其他 Logo |
| 删除 | 删除默认 Logo 后，剩余的第一个 Logo 提升为默认 |
| Logo ID | 由 Waffo 在**保存时**分配，而不是上传时 |

ID 格式稳定且可预测：

| 级别 | 格式 | 示例 |
| - | - | - |
| MID | `logo_M{n}` | `logo_M1`、`logo_M2` |
| SubMID | `logo_S{SubMID 的后 3 位}_{n}` | `logo_S417_1`、`logo_S417_2` |

ID 在你的账户内唯一，Logo 一旦保存，其 ID 永不复用。

## 我有三个 Logo，但最新的是 logo\_M5，这是 bug 吗？

不是。序号从该 MID 或 SubMID 上曾使用过的最大编号继续分配，已删除的 Logo 保留其编号。删除 `logo_M2` 和 `logo_M3`，再上传一个新 Logo，它会成为 `logo_M4`——这些空缺是刻意永久保留的，这样你在集成中硬编码的 ID 永远不会指向另一张图片。

## 我能在订单上直接传 Logo，而不是用 Logo ID 吗？

可以，而且两者用**同一个字段**——`brandInfo.cashierLogoUrl`。按前缀路由：

| 值的开头 | 视为 | 行为 |
| - | - | - |
| `http://` 或 `https://` | Logo **URL** | 该次收银会话使用这张图片 |
| `logo_` | Logo **ID** | 使用匹配的已上传 Logo |
| 其他任何内容 | 无效 | 静默丢弃；订单仍会创建 |

Logo URL 优先于 Logo ID，因此传 URL 会在该会话中完全覆盖你的 Portal Logo 列表（你的 Portal *样式*配置仍然应用）。找不到可用 Logo 时的回退：

* ID 不存在，或属于已删除的 Logo → 使用**默认** Logo。
* 完全没传 Logo → 使用**默认** Logo。
* URL 未通过校验 → 丢弃，然后应用同样的回退。
* 任何地方都没配置 Logo → 不显示 Logo。

## 如果我只有 Logo 或只有名称，头部会显示什么？

四种组合，全部支持：

| Logo | 商户展示名称 | 头部显示 |
| - | - | - |
| 有 | 有 | Logo 在左，名称在旁 |
| 有 | 无 | 仅 Logo |
| 无 | 有 | 仅名称 |
| 无 | 无 | 没有商户标识区块——页面以金额开头 |

显示的名称始终是**收银台展示名称**（依次来自订单、你的 SubMID、你的 MID）。你在 KYB 登记的法定名称在这里永远不会使用。涉及披露脚注的唯一例外，见收银台页面生命周期与收据页面。

## 实时预览有多准确？

预览在表单旁渲染一个真实的收银台页面，因此颜色、尺寸、Logo、头部布局和支付方式排序都会随编辑更新。其下有 Mobile / Desktop 切换，预览跟随你在 **Cashier Ranking** 标签页选择的国家，并以你的 Portal 界面语言渲染。

在把差异当作 bug 上报之前，有两个限制值得了解：

* 预览无法知道**按订单的可用性**。真实收银台页面会把暂时不可用、或不适用于特定订单的支付方式置灰或去掉；预览不会，因此真实买家可能看到略少的选项。
* 预览和真实收银台共用**同一个单一平铺列表可展示支付方式数量的上限**。如果你关闭按国家分组，且去重后的列表超过该上限，预览和真实页面都会回退到按国家分组——越过上限时 Portal 会用确切数字警告你。

## 我团队里谁能修改这些设置？

保存受单一的收银台客制化编辑权限控制。没有该权限的账户整个页面为**只读**：预设按钮、颜色选择器、滑块、开关、拖拽手柄和上传全部禁用，没有 Save 按钮，SubMID 列表提供 **Detail** 而不是 **Edit**。页面本身仍可查看。

按角色（依 Portal 角色集定义）：

| 角色 | Customization 页面 |
| - | - |
| Super Admin | 查看和保存 |
| Admin | 查看和保存 |
| General | 仅查看 |
| Read-only | 仅查看 |
| Developer | 仅查看 |
| Dispute Manager | 无权访问 |

## 客制化更改需要 Waffo 审批吗？

不需要。保存即时生效且完全自助——没有审核环节。如果保存被拒绝，那是你输入的值的校验问题，不是审批。

***

仍然没有渲染出你期望的效果？请[联系支持](mailto:support@waffo.com)，附上订单 ID，以及——如果你在订单上发送了样式——你发送的确切 `cashierAppearance` 字符串——最常见的原因是订单级的值悄悄覆盖了 Portal。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.