用户手册 — 商户门户（Merchant Portal）
P2P 转账平台 · 中文版
关于截图的说明： 本手册中的所有截图均为英文（与系统实际抓取的界面一致）。因此，界面上的菜单名与按钮名保留英文，方便您与实际画面一一对应；说明文字则为中文。
商户门户（Merchant Portal）是将客户的充值与提现接入 P2P 平台的企业后台。您的团队可在此监控交易、处理提现、审核付款凭证（回单）、管理用户与员工、跟踪计费，并配置资金的路由方式。
本手册以操作者优先（operator-first）为原则：先介绍日常业务流程；技术集成主题——API 密钥、合作方 API、webhooks——放在附录 A — 开发与集成。
目录
- 开始之前 — 核心概念
- 1. 登录
- 2. 您的仪表盘
- 3. 交易（Transactions）
- 4. 提现（Withdrawals）
- 5. 凭证审核（Slip review）
- 6. 用户（Users）
- 7. 计费与使用额度
- 8. 设置（Settings）
- 9. 子商户（Sub-merchants）
- 10. 团队（Team）
- 11. 优先级授予（Priority grants）
- 附录 A — 开发与集成
- 附录 B — 术语表
本版本说明： 少数页面所记录的功能仍在完善中，凡出现之处均以开发中标注清楚。凡被如此标注的功能，尚不保证能够保存更改。
开始之前 — 核心概念
有几个概念几乎能解释每一个页面。请先读一遍，门户其余部分便会豁然开朗。
平台从不持有资金。 平台仅充当账本（ledger）和撮合方（matchmaker）。当一笔提现被处理时，资金在两个人之间银行对银行直接划转——平台只记录这笔转账，从不经手现金。因此，"处理提现（fulfilling a withdrawal）"指的是上传一笔已完成转账的凭证（由您或撮合到的卖方完成），而非点击"发送资金"按钮。
充值转化为额度；提现消耗额度。
- 充值（deposit）会向您商户资金池中某位用户的钱包增加额度。客户向银行账户（或支付网关）付款并上传凭证；凭证核验通过后，额度即到账。
- 提现（withdrawal）消耗该额度。平台完成撮合，对手方划转现金，随后由您（或平台）以凭证确认。
额度类型 — 您会在用户余额上看到这些：
- REAL — 真实、可提现的额度。撮合与计费均围绕它进行。
- POINT — 促销性、不可提现的额度。通过 API 设置，从不进入撮合。
- PLATFORM_CREDIT — 独立资金池，仅由管理员（admin）处理。
充值生命周期 — 您会在交易上看到的状态：
创建预留（Reservation created）→ 待上传凭证 → 已上传凭证 → 核验中 → 已结算（settled）（额度到账）。
一笔充值也可能到账金额超出（over）预留金额（仅按预留金额入账，超出部分被标记）或不足（under）（仅按实际到账金额入账）。
谁能做什么 — 员工角色。 本手册中的每项操作都受角色限制：
| 权限 | OWNER | OPERATOR | VIEWER |
|---|---|---|---|
| 查看仪表盘、交易、用户、计费 | ✅ | ✅ | ✅ |
| 处理提现 · 审核凭证 | ✅ | ✅ | — |
| 显示用户完整银行账号 | ✅ | ✅ | — |
| 轮换 API 密钥 / HMAC · 集成测试 · webhooks | ✅ | ✅ | — |
| 管理银行账户、网关、优先级阈值 | ✅ | — | — |
| 邀请员工 / 变更角色 · 子商户 | ✅ | — | — |
1. 登录
/merchant/login 的商户登录界面。每次登录、每位员工都需两步：
- 在
/merchant/login输入邮箱 + 密码。 - 输入身份验证器应用中的 6 位验证码（Google Authenticator、Authy、1Password 等）。
首次登录？ 如果由所有者（owner）或您的分销商（reseller）邀请您加入，首次登录将使用临时密码，并引导您完成初始设置（onboarding）：设置永久密码（至少 12 个字符，含字母和数字），用身份验证器应用扫描 TOTP 二维码，并确认一次验证码。之后即进入仪表盘。
丢失身份验证器？ 所有者可在 Team（见第 10 节）中重置您的凭据。系统将签发新的临时密码并清除您的 2FA，以便重新绑定。
2. 您的仪表盘
仪表盘是您一目了然的运营视图。它显示需要关注的数量——待处理提现（pending withdrawals）、待处理事项（pending fulfilments）、您的可用平台额度（available platform credit），以及最近的优先级授予（priority grants）——每张卡片都直接链接到相应队列。
3. 交易（Transactions）
Transactions（/merchant/transactions）是您资金池的完整资金流水。可按 ID、金额或电话号码搜索；按类型（充值、充值分支（deposit legs）、提现等）和日期范围筛选。所有者还可按子商户（sub-merchant）下钻查看。
行操作取决于交易类型：
- 充值 / 预留（deposit / reservation）提供 Cancel & release——释放持有的预留，并解除其与已撮合提现的绑定。
- 提现（withdrawal）提供 Fulfil——见第 4 节。
交易详情
打开一笔交易会显示完整全貌：账本记录（ledger entry）、上传的凭证图片及其解析出的付款方与收款方、（掩码后的）付款银行账户，以及结算该笔交易的资金来源充值（funding deposits）列表。有两个信号值得了解：
- 超额（over-cap）——付款方发送金额多于预留金额。仅按预留金额入账；多余部分被记录，供您对账。
- 不足（under-cap）——付款方发送金额少于预留金额。仅按实际到账金额入账；差额视为从未收到。
4. 提现（Withdrawals）
Withdrawals 队列列出待处理的提现订单，按优先级层级（priority tier）排序。每行显示金额、发起提现的客户（以您自己的用户 ID 标识）、子商户标签（如有）以及请求日期。
处理提现
处理是一个凭证或跳过（slip-or-bypass）的二选一——两者只做其一：
- 上传凭证 — 显示资金已到达客户的银行转账回单。
- 附理由跳过（bypass with a reason） — 用于在常规凭证流程之外完成的结算（例如现金支付）。您必须记录原因。
提现支持部分完成（partial fills）：若您处理的金额少于全额，剩余部分将退回客户钱包，您可使用 early-success 关闭一笔您已满意的部分提现。每次处理都会通过 withdraw.notify webhook 通知您的系统。
5. 凭证审核（Slip review）
Slip review 是您核验充值凭证之处。它分两部分——reservations（直接充值）和 legs（被拆分到多个银行账户的充值）。您在此的主要操作是拒绝（reject）未通过的凭证（附理由）。普通凭证的批准是管理员的职责，但有几种明确的例外由您处理：认证批准（attestation）和超额判定。
每个条目上的实用工具：
- Re-verify — 若 QR 或回单无法读取，在上传更清晰的图片后重新运行提取。
- Late-slip upload — 若预留在客户提交凭证前已过期，上传迟到的凭证，将其恢复为一笔可审核的新充值。
评分发现（Score findings）
Score findings（侧栏中名为 "Score findings"）列出在自动 QR/OCR 置信度上得分较低的凭证——显示来源、充值人、置信度分数以及不匹配的字段数量。可按 For review、Reviewed 或 All 筛选；Mark reviewed 用于记录您已知悉某项发现。
6. 用户（Users）
Users 列出与您商户关联的客户。可按邮箱、显示名或您自己的用户 ID 搜索。在此您还可以：
- 签发注册链接（signup links） — 一次性链接，将客户与您的商户关联（可重新签发）。
- 撤销同意（revoke consent） — 断开某用户的关联（需键入
REVOKE确认）。
用户详情
［有数据的截图待补 — 用户详情页说明如下；该商户的演示数据尚无可用截图。］
用户页面显示其资料、多资金池钱包（multi-pool wallet）（REAL / POINT / PLATFORM_CREDIT 余额）以及最近的提现。银行账号会掩码为后四位；OPERATOR 或 OWNER 可显示（reveal）完整账号，该操作会被记入审计日志。
⚠️ 生产环境说明： 完整银行账号显示在开发环境中可用，但目前在生产环境中被禁用，正等待 KMS 密钥服务（ADR-0102）。
7. 计费与使用额度
Billing 显示您的使用量以及据此计算的费用，采用曼谷时间（GMT+7）。两张头部卡片给出今日和本月至今（month-to-date）的使用量与费用；下方有一个粒度切换（小时 / 天 / 周 / 月）和日期范围，用于驱动账本表格。费用在读取时根据您生效的费率表计算。
使用额度（Usage credit）
Usage credit 是平台用来扣取您费用的预付余额。卡片显示您的当前余额、低余额阈值以及最近活动。使用 Top-up request 增加额度（由管理员审核）。历史表格记录每一笔充入、扣减与调整。
8. 设置（Settings）
Settings 显示您的商户配置——显示名、slug、状态、webhook URL、速率限制（rate limit）以及 DPA 接受情况。其中大部分由管理员管理；下方子页面才是您的所有者可控制的部分。
银行账户（Bank accounts）
您的路由池（routing pool）是客户充值以轮询方式导向的一组银行账户。所有者可启用/停用账户，并编辑您自己的账户；新增账户由管理员完成。
支付网关（Payment gateways）
如果您的充值通过支付网关，此页面会列出网关凭据、其状态及配对的路由槽位。所有者可启用/停用它，并重命名其显示标签。系统从不显示密钥（secret）。
优先级阈值（Priority thresholds）
一组四级、严格递增（strictly-increasing）的金额，用于划分哪些充值获得优先安排。
⚠️ 开发中： 此配置页面仍在开发中（Phase C），可能尚不接受更改。
9. 子商户（Sub-merchants）
如果您向自己的下游企业转售，Sub-merchants 允许所有者创建并跟踪它们。每个子商户都有唯一编码、显示名以及各自的使用额度余额，该余额由您从母池分配。整个门户中的交易与用户均可按子商户筛选。
10. 团队（Team）
Team 是所有者管理员工之处。邀请新成员（系统会显示一次性凭据及 TOTP 二维码供交接），变更成员角色，或重置成员凭据。有防护机制保护您：您不能变更自己的角色，也不能将最后一位所有者锁定在外。
11. 优先级授予（Priority grants）
Priority grants 列出按用户设置的优先级覆盖（per-user overrides）。
⚠️ 开发中： 创建与撤销授予尚未启用（Phase C）；目前列表仅供查看。
附录 A — 开发与集成
以下页面面向将您的系统与平台集成的工程师。业务操作者可跳过本附录。
API 密钥与 HMAC 密钥
此页面显示您 API 密钥的指纹（fingerprint）（从不显示完整密钥），并允许您轮换（rotate）API 密钥与 HMAC 签名密钥。轮换时，新值仅显示一次——请立即复制。新旧值均保持有效 24 小时，以便您零停机地完成切换。
集成测试控制台（Integration test）
供开发者使用的沙盒，含两个选项卡：
- Webhooks — 向您的 webhook URL 发送合成事件，使用真实的 HMAC 签名，以测试您的接收端。
- API — 直接在浏览器中用您的 API 密钥调用合作方 API，配有按流程排序的参考文档，以及一个 LLM 提示词生成器，帮助您搭建集成。
Webhook 投递日志
完整的投递日志——包括已投递（delivered）和失败（failed）的事件。可按状态、事件类型和日期筛选。有两种重发操作：
- Retry — 将同一笔失败投递重新入队。
- Resend — 将一笔已投递的事件复制为一次全新投递（原记录保留）。
合作方 API 一段话概览
您的后端调用平台的合作方 API 来创建充值与提现，以及查询余额。平台会以 deposit.notify 和 withdraw.notify（统一结算通知）回调您，并在提现前以同步的 credit.check 确认用户余额。每一个出站 webhook 都经过 HMAC-SHA256 签名——请在您这一侧用您的 HMAC 密钥验证签名（切记该密钥以 base64 提供，验证前需解码为原始字节）。每一个变更类调用都需要一个 idempotency key（幂等键）。
附录 B — 术语表
- Reservation（预留） — 为即将到来的充值保留的槽位，等待客户的凭证。
- Leg（分支） — 一笔充值被拆分到多个目标银行账户中的一部分。
- Over-cap / under-cap（超额 / 不足） — 付款方发送的金额多于 / 少于预留金额。
- Fulfilment（处理/履行） — 证明提现的现金确已划转（凭证或已记录的跳过）。
- Usage credit（使用额度） — 您的预付余额，平台从中扣取费用。
- Sub-merchant（子商户） — 您转售给的下游企业，归属于您的商户之下跟踪。
- REAL / POINT / PLATFORM_CREDIT — 用户钱包可持有的三种额度类型。