EasyCards 商户后台操作手册#

本手册面向 EasyCards Portal 的商户管理员，按实际页面逻辑说明入户、资金账户、团队、卡片和系统设置操作。持卡人接受邀请、完成个人 KYC 和查看本人卡片时使用 H5，不使用 Merchant Portal。

操作原则： 页面显示“提交成功”只说明请求已受理。凡是显示 PENDING、PROCESSING、CONFIRMING 或“处理中”的操作，都必须回到对应列表、详情或账本确认最终状态，不要因为等待时间较长而重复提交。

文档示例安全声明： 本手册截图中的充值地址、二维码、账户名称、余额、卡号、API Key、Webhook URL、Secret 及其他敏感信息均为虚构、遮盖或脱敏的演示数据，仅用于说明页面操作。

**禁止将文档中的任何地址、二维码、密钥或卡信息用于真实转账、充值、支付或生产接口调用。**真实操作必须登录 EasyCards Portal，并以当前账户页面实时显示的信息为准。

Portal 快捷入口（请先登录，页面仍受账户权限控制）：

1. 使用范围与权限#

1.1 Portal 与 H5 的分工#

vcc_member 登录 Merchant Portal 时会被引导至 H5。商户管理员不要把 Portal 登录地址发送给持卡人。

1.2 菜单和按钮由权限决定#

Portal 会同时根据当前账户、角色和权限显示菜单与操作按钮，因此不同用户看到的页面可能不同：

• 团队管理需要管理员角色，并具备团队管理权限；
• 开卡还需要卡片创建权限；
• 共享账户查看、资金划入划回、额度调整分别需要对应权限；
• 储值卡直接充值、提交充值申请和审批充值申请是三种不同权限；
• 冻结、解冻、API Key 和 Webhook 管理均受独立权限控制。

如果本手册中的菜单或按钮没有显示，先让账户 Owner 核对当前登录账户、角色和权限；不要通过反复刷新或重复提交处理权限问题。

1.3 同步响应与异步结果#

flowchart LR
  A[在 Portal 提交操作] --> B[同步返回受理结果]
  B --> C{是否已是最终状态}
  C -->|SUCCESS / COMPLETED| D[核对余额、卡片或记录]
  C -->|PENDING / PROCESSING / CONFIRMING| E[等待异步处理]
  E -.状态更新.-> F[刷新列表或详情]
  F --> C
  C -->|FAIL / FAILED / REJECTED| G[查看失败原因并按提示处理]

2. 从注册到用卡#

flowchart TD
  A[注册商户账户] --> B[验证工作邮箱]
  B --> C[登录并完成 TOTP]
  C --> D{当前账户启用 Portal KYB?}
  D -->|是| E[提交企业 KYB]
  E -.异步审核.-> F[KYB 通过]
  D -->|否| G[进入 Dashboard]
  F --> G
  G --> H[联系 EasyCards BD]
  H -.运营配置.-> I[卡产品显示在 Portal]
  I --> J[向资金账户充值]
  J --> K[邀请团队成员]
  K -.邮件邀请.-> L[成员在 H5 激活并完成个人 KYC]
  L -.状态更新.-> M[管理员开卡与管理卡片]

完成标准不是“能够登录”，而是当前账户已经完成适用的 KYB、卡产品已经显示、资金可用余额已经到账，并且相关管理员具备所需权限。

3. 注册、邮箱验证与登录#

3.1 注册商户账户#

打开 EasyCards 注册页面：

1. 填写商户名称和工作邮箱。
2. 设置 8–128 位密码，且同时包含大写字母、小写字母、数字和特殊字符。
3. 阅读服务条款和隐私政策后提交注册。
4. 注册成功后按页面提示进入邮箱验证流程。

请使用可以持续接收安全通知的工作邮箱。邮箱以后用于登录、验证和重要操作通知。

3.2 验证工作邮箱#

1. 打开 EasyCards 发送的验证邮件并完成验证。
2. 返回验证页面，点击继续或刷新验证状态。
3. 未收到邮件时可以重新发送；页面会显示重新发送的冷却时间。
4. 验证成功后，系统会继续登录或返回登录页。

邮箱验证尚未完成时，Portal 不会把该账户视为可正常登录账户。验证会话失效时，返回登录页重新发起流程。

3.3 登录和双因素验证#

1. 打开 EasyCards 登录页面。
2. 输入已验证的邮箱和密码。
3. 如果页面要求首次绑定 TOTP，使用认证器应用扫描二维码，并输入 6 位验证码完成绑定。
4. 已绑定 TOTP 的用户输入当前 6 位验证码完成登录。
5. 同一用户有多个账户时，在账户选择弹窗中确认本次需要操作的账户。

后续资金、开卡、额度、卡状态和密钥操作均可能再次要求 6 位验证码。忘记密码时使用登录页的“忘记密码”入口，不要新注册重复账户。

4. Portal 企业 KYB#

4.1 判断当前账户是否启用 KYB#

Portal KYB 是按账户配置启用的：

• 已启用且尚未认证：登录后会自动进入 KYB，不能直接进入业务页面；
• 未启用：登录后直接进入 Dashboard；
• 已认证：正常进入 Dashboard。

因此，只有 Portal 实际显示 KYB 页面时才按本章操作。本手册不额外添加页面没有展示的提交方式或材料限制。

4.2 选择注册国家或地区#

1. 在 KYB 引导页选择企业注册国家或地区。
2. 查看页面根据该地区返回的必需材料和可选材料。
3. 如需核对样例，使用页面提供的材料样例入口。
4. 确认选择后开始填写。

国家或地区在 KYB 记录建立后不能在当前流程中自行切换，提交前务必核对。

4.3 完成四步资料#

依次完成：

1. 基本信息：按页面字段填写企业基本资料和地址。
2. 公司文件：上传页面当前要求的企业文件。
3. 业务信息：填写业务情况及页面要求的补充信息。
4. 人员信息：添加董事、股东和企业联系人，并填写对应身份和持股信息。

Portal 企业 KYB 文件控件接受 PDF、JPG/JPEG 和 PNG。实际必填字段、文件数量和材料要求由页面根据注册地区动态返回，以当前页面为准。

4.4 提交、审核和补件#

• PENDING：资料已经提交，正在异步审核；等待结果，不要重复提交。
• APPROVED：确认审核结果后进入 Dashboard。
• REJECTED：先查看按步骤分组的具体问题和审核说明，再确认结果并修改对应字段或文件。

补件完成后重新提交并继续等待审核。只有 Portal 显示通过并允许进入业务页面，才表示企业 KYB 流程完成。

5. 开通卡产品#

卡产品由 EasyCards 运营团队配置，商户不能仅通过 Portal 自行启用新产品。

1. 联系您的 EasyCards BD，说明需要的产品模式和使用需求。
2. 按要求确认产品资料。
3. 等待运营完成配置。
4. 进入 CARD → 卡产品，按产品模式或状态筛选。
5. 核对卡类型、产品代码、共享卡/储值卡模式、币种、充值区间、费用和启用状态。

只有状态为启用的产品才应进入后续邀请或开卡流程。如果产品不存在、被禁用或字段不符合确认结果，联系 BD 核对配置，不要用其他产品代替。

6. Dashboard#

Dashboard 用于快速查看当前账户的运营状态，包括账户余额、活跃和冻结卡片、交易成功情况、余额分布、提醒和最近交易。

建议每次登录后先完成三项检查：

1. 查看可用余额是否足以支持计划中的开卡和充值。
2. 查看冻结卡片和失败交易提醒。
3. 查看最近交易后，再进入对应卡片或交易页面处理。

Dashboard 是汇总视图，不代替账务和业务终态核对。资金以账户列表、充值记录和余额明细为准；卡片以卡片列表或详情为准；交易以卡交易明细为准。

7. 资金账户与数字资产充值#

7.1 查看账户和余额#

进入 财务 → 账户 → 账户列表：

1. 确认当前登录账户。
2. 在数字资产账户和法币账户之间切换。
3. 核对币种、账户名称、余额和可用余额。
4. 从目标账户的操作栏进入充值、兑换、提现或账本明细；实际可用操作以权限和页面按钮为准。

“余额”与“可用余额”可能不同。任何资金操作都应以可用余额判断能否继续。

7.2 获取 USDT 充值地址#

1. 在数字资产账户中找到 USDT，点击“充值”。
2. 选择充值币种和网络。
3. 核对页面显示的币种、网络和完整地址。
4. 使用复制按钮复制地址，不要手工输入。
5. 在转出端再次核对所选网络与 Portal 完全一致。

当前页面提供的网络组合以充值弹窗为准；页面说明 TRON 网络仅支持 USDT，Ethereum ERC20 网络支持 USDT 和 USDC。

请勿向下图地址转账： 下图二维码和地址仅为文档示例，不能接收真实资金。发起充值时必须从当前登录的 Portal 重新获取并核对真实地址。

USDT 资金安全提醒

首次使用或充值地址发生变化时，必须先进行小额测试。只有充值记录和目标账户可用余额都确认到账后，才可以继续较大金额充值。币种、网络或地址不一致可能导致资金无法找回。

7.3 小额测试和到账确认#

flowchart LR
  A[复制 Portal 当前地址] --> B[核对币种和网络]
  B --> C[发起小额 USDT 测试]
  C -.链上确认.-> D[充值记录出现]
  D --> E{状态}
  E -->|CONFIRMING| F[等待确认并刷新]
  F -.确认更新.-> E
  E -->|CONFIRMED| G[核对可用余额]
  E -->|FAILED| H[保存交易哈希并查明原因]
  G --> I[确认测试完成]

进入 财务 → 账户 → 充值记录，按币种、网络或状态查找本次充值，并核对：

• 充值单号；
• 金额和币种；
• 网络和交易哈希；
• 确认数；
• 当前状态和时间。

记录显示 CONFIRMED 后，返回账户列表确认目标币种可用余额已经增加。仅有交易哈希、仅有充值记录或仅看到处理中状态，都不能作为到账完成标准。

7.4 保存并再次使用地址#

小额测试成功后，由商户自行安全保存已验证的充值地址。

每次后续充值前仍要重新打开 Portal，并重新核对币种、网络和当前地址。只要其中一项与保存信息不同，就停止转账并以 Portal 当前显示为准重新验证。

7.5 余额明细和异常核对#

进入 财务 → 账户 → 余额明细，可按流水类型、日期等条件查询，并导出账本 CSV。核对异常时使用同一笔业务的充值单号、交易哈希或业务编号关联以下信息：

1. 充值记录状态；
2. 余额明细；
3. 账户可用余额。

记录已经确认但可用余额仍未变化时，保留交易哈希和相关编号，不要重复充值。

8. 卡产品和持卡人#

8.1 查看产品条件#

进入 CARD → 卡产品，使用关键字、卡模式和状态筛选。页面显示的信息包括：

• 卡产品名称、卡类型 ID 和产品代码；
• 虚拟卡或实体卡；
• 共享卡（BUDGET_CARD）或储值卡（PREPAID_CARD）；
• 币种和单次充值范围；
• 开卡、KYC、充值、跨境、汇率等适用费用；
• 启用或禁用状态。

开卡前应先核对模式、币种、费用和状态，不能只按产品名称选择。

8.2 查看持卡人#

进入 CARD → 持卡人查看已建立的持卡人及其 KYC 状态、姓名、邮箱和电话。持卡人资料主要由团队邀请、H5 激活和 KYC 流程建立；本页面用于查询和核对，不应把“列表中出现”理解为已经完成开卡。

9. 团队邀请与 H5 交接#

9.1 邀请团队成员#

具备团队管理权限的管理员进入 CARD → 团队 → 团队成员：

1. 点击邀请成员。
2. 填写持卡人的工作邮箱。
3. 选择已经启用的卡产品。
4. 确认角色为“持卡成员”。当前页面只提供该成员角色。
5. 输入管理员的 6 位双因素验证码并提交。
6. 返回列表核对邀请状态和邮件投递状态。

创建邀请的同步成功响应只代表邀请记录已经建立。邮件发送、成员激活、个人 KYC 和开卡均是后续步骤。

9.2 管理邀请和成员访问#

列表可显示邀请状态、邮件状态和访问状态：

• PENDING：等待成员接受；可按页面按钮重新发送或撤销；
• ACCEPTED：成员已经接受邀请；
• EXPIRED / REVOKED：原邀请不能继续使用，需要按实际情况重新邀请；
• 邮件投递状态为发送中、已发送、失败或跳过时，以列表当前状态判断是否需要重新发送；
• 已接受成员可以被禁用或恢复；禁用操作可能同时处理该成员的卡片，应查看返回的卡片处理结果。

9.3 持卡人在 H5 完成的步骤#

管理员应让持卡人使用邀请邮件中的 H5 链接：

1. 核对邀请绑定邮箱并设置登录密码。
2. 登录 H5；首次登录时绑定 TOTP，以后使用 6 位验证码验证。
3. 按 H5 页面完成姓名、电话、出生日期、居住地址、国籍等基础 KYC。
4. 产品要求额外身份资料时，继续完成补充 KYC 和文件上传。
5. 查看开卡申请状态；需要补充资料时按失败原因修改后重新提交。

H5 KYC 文件支持 JPG/JPEG、PNG 和 PDF，单个文件最大 2 MiB。持卡人端完整步骤见 持卡人 H5 使用手册。

9.4 管理员为已接受成员开卡#

当成员状态为已接受且未被禁用，并且管理员具备开卡权限时：

1. 在团队成员列表点击“开新卡”。
2. 选择目标卡产品，并核对模式、币种和开卡费用。
3. 输入 6 位双因素验证码并提交。
4. 记录页面返回的开卡编号和状态。
5. 如果返回需要 KYC，通知成员回到 H5 完成资料。
6. 在对应共享卡或储值卡列表按 PENDING、FAIL、SUCCESS 查看最终结果。

sequenceDiagram
  participant A as 商户管理员
  participant P as EasyCards Portal
  participant H as 持卡人 H5
  participant S as EasyCards 服务
  A->>P: 创建邀请并选择卡产品
  P->>S: 提交邀请
  S-->>P: 同步返回邀请记录
  S-->>H: 异步发送邀请邮件
  H->>S: 激活账户并提交个人 KYC
  S-->>H: 同步返回受理状态
  S-->>P: 异步更新成员与 KYC 状态
  A->>P: 为已接受成员提交开卡
  P->>S: 提交开卡申请
  S-->>P: 同步返回开卡编号和初始状态
  S-->>P: 异步更新审核和发卡状态
  A->>P: 刷新卡片或申请列表
  P->>S: 查询当前结果
  S-->>P: 返回最终状态和 card_id / 失败原因

10. 共享账户与已发共享卡#

10.1 查看共享账户#

进入 CARD → 共享卡 → 共享账户，核对：

• 账户总余额、可用余额和交易中金额；
• 共享账户状态；
• 绑定的资金账户；
• 是否存在超限金额。

共享账户未绑定当前资金账户、状态不可操作或处于超限状态时，页面会阻止资金操作，应先按页面原因处理。

10.2 划入或划回资金#

具备共享账户资金权限时：

1. 点击“划入共享账户”或“划回主钱包”。
2. 划入前核对绑定资金账户和其可用余额。
3. 输入正数金额和 6 位双因素验证码。
4. 提交后查看返回状态。
5. PENDING 时等待并刷新，不要立即重复提交。
6. 通过共享账户余额和共享账户明细确认最终结果。

SUCCESS 才表示操作已经成功完成；FAIL 应查看错误信息；PENDING 只表示已进入异步处理。

10.3 查看卡片和开卡申请#

进入 CARD → 共享卡 → 共享卡：

• SUCCESS 查看已发卡片；
• PENDING 查看仍在处理的开卡申请；
• FAIL 查看未完成的申请及失败原因。

已发卡列表可以按持卡人或卡片关键字查询，并查看卡状态、配置额度、可用额度和使用情况。开卡结果以列表当前状态和卡片详情为准。

10.4 管理已发共享卡#

根据权限和卡片状态，管理员可以：

• 打开卡片详情并查看交易；
• 通过 6 位双因素验证码查看 PAN、有效期和 CVV；敏感信息 2 分钟后自动清除；
• 对同时处于卡片有效和额度有效状态的卡片增加或减少额度；
• 冻结或解冻卡片。

额度调整和状态变更都可能返回 PENDING。提交后在卡片详情、额度记录或共享账户明细中确认终态。不要将弹窗关闭或成功提示当作额度已经最终生效。

10.5 核对共享账户明细#

进入 CARD → 共享卡 → 共享账户明细，可按卡片、流水类型和来源查询。重点核对资金划入划回、额度预留与确认、交易、退款和费用记录，并使用关联编号定位同一业务。

11. 储值卡#

Portal 的父菜单显示“预付卡”，卡片列表显示“储值卡”；两者均指 PREPAID_CARD 模式。

11.1 查看卡片和申请#

进入 CARD → 预付卡 → 储值卡：

1. 使用持卡人关键字、卡号后四位和申请结果筛选。
2. SUCCESS 查看已发卡片。
3. PENDING 查看处理中申请。
4. FAIL 查看失败原因。

新的储值卡通过团队成员列表的“开新卡”流程提交。

11.2 查看和管理卡片#

在储值卡列表打开操作菜单或卡片详情，可以在具备对应权限时：

• 查看持卡人、脱敏卡号、余额、有效期和当前状态；
• 通过双因素验证查看敏感卡信息，信息 2 分钟后自动清除；
• 查看该卡交易和充值申请历史；
• 冻结或解冻卡片。

操作前至少核对持卡人邮箱、卡号后四位和卡片状态，避免操作错误卡片。

11.3 直接充值或提交充值申请#

卡片详情会根据权限显示不同操作：

• 具备直接充值权限：输入金额和 6 位验证码后直接提交充值；
• 仅具备充值申请权限：输入金额、可选备注和 6 位验证码后提交申请，等待管理员审批；
• 两项权限均没有：页面不显示充值操作。

直接充值仍可能返回 PENDING。提交后刷新卡片余额并查看充值记录；FAIL 时查看失败原因，不能仅凭提交提示判断成功。

12. 充值申请审批#

12.1 查看申请#

具备申请查看或审批权限的管理员进入 CARD → 团队 → 申请记录。页面按 PENDING、APPROVED 和 DENIED 分类，并展示申请人、持卡人、金额、备注和时间。

审批前必须核对：

1. 持卡人邮箱和目标卡片；
2. 申请金额和币种；
3. 商户资金账户可用余额；
4. 是否存在重复或异常申请。

12.2 批准或拒绝#

• 批准：输入管理员 6 位双因素验证码。批准会继续执行卡片充值。
• 拒绝：填写拒绝说明后提交，便于申请人了解原因。

flowchart LR
  A[持卡人或操作员提交充值申请] --> B[PENDING]
  B --> C{管理员决定}
  C -->|拒绝| D[DENIED]
  C -->|批准 + MFA| E[APPROVED]
  E --> F{充值执行状态}
  F -->|PENDING| G[等待并刷新]
  G -.状态更新.-> F
  F -->|SUCCESS| H[核对卡片余额]
  F -->|FAIL| I[查看充值失败原因]

APPROVED 只是审批结果，还要继续查看充值执行状态：

• APPROVED / PENDING：已批准，充值仍在处理；
• APPROVED / SUCCESS：充值执行成功，再核对卡片余额；
• APPROVED / FAIL：审批通过但充值失败，查看充值单号和失败原因。

失败时不要再次批准原申请；先确认原充值单的最终状态，再决定是否新建申请。

13. 卡交易明细#

进入 CARD → 卡交易明细，可按持卡人、卡号后四位、共享卡/储值卡模式、交易类型、状态和日期范围筛选。

页面显示持卡人、卡片、交易类型、金额、商户信息、状态和时间。交易核对时：

1. 先按持卡人或卡片缩小范围。
2. 核对交易时间、金额、币种、方向和状态。
3. 失败或处理中交易不要只看金额，应同时查看状态和关联卡片。
4. 需要离线核对时，可以按当前筛选条件导出 CSV 或 Excel；当前单次导出最多获取 500 条。

卡片余额、共享账户明细和交易明细用途不同。出现差异时按交易编号、卡片 ID 和时间关联核对，不要用单一页面替代完整核对。

14. 安全设置、API Key 与 Webhook#

14.1 管理安全设置#

进入 系统 → 设置 → 安全设置，可管理密码和 TOTP 状态。资金、开卡、卡状态和密钥管理依赖双因素验证，管理员应先确保认证器可正常生成验证码。

14.2 创建和管理 API Key#

进入 系统 → 设置 → API 密钥：

1. 点击“创建密钥”，填写易于识别的名称。
2. 仅勾选本次集成实际需要的权限。
3. 如调用卡敏感信息接口，可按实际需要绑定卡敏感信息公钥；这是可选字段。
4. 按需填写 IP 白名单。
5. 设置到期日，或明确选择无有效期。
6. 输入 6 位双因素验证码并创建。
7. 立即复制并安全保存 API Key；完整密钥只展示一次。

创建后可编辑配置、轮换或禁用：

• 轮换会使旧密钥失效；应先准备调用方切换方案；
• 禁用后该密钥不能继续调用接口；
• API Key 不得放入前端代码、聊天记录或版本库。

需要开发接入时查看 VCC 对接手册 和 API 参考，本操作手册不重复接口字段。

14.3 配置 Webhook#

进入 系统 → 设置 → Webhook 配置：

1. 新建 Webhook。
2. 填写公网可访问、能够接收 POST JSON 的 URL。
3. 至少选择一个页面提供的 VCC 事件。
4. 选择启用或禁用状态。
5. 可以填写自定义 Secret；留空时由系统生成。
6. 保存后立即复制 Secret；系统生成的 Secret 只展示一次。

通知规则：

• EasyCards 使用 POST 发送 JSON；
• 接收端返回任意 2xx 表示投递成功；
• 非 2xx 或超时会重试，最多 10 次、最长 72 小时；
• VCC Webhook 统一使用 X-Webhook-Signature、X-Webhook-Id、X-Delivery-Id 和 X-Webhook-Event；
• 使用保存的接口响应或 Portal 最终展示的 secret 按 HMAC-SHA256 验签，不要直接使用创建请求中提交的原始自定义 Secret。

Webhook 是异步通知，不应作为唯一账务依据。收到事件后仍要根据事件中的资源标识查询或核对 Portal 当前状态。验签和事件示例见 Webhook 事件与通知规则。

14.4 查看投递记录#

进入 系统 → 设置 → 投递记录：

1. 按 Webhook ID 或状态筛选。
2. 查看 PENDING、DELIVERED 或 FAILED。
3. 打开详情核对请求 URL、请求 Headers、请求 Body、HTTP 状态码和响应 Body。
4. 失败或等待重试时查看尝试次数、上次错误、上次尝试时间和下次重试时间。

排查顺序应为：目标 URL 可访问 → 接收端是否返回 2xx → 验签是否使用当前 Secret → 业务处理是否幂等。不要通过重复创建 Webhook 解决单次投递失败。

15. 完成确认与异常处理#

15.1 各操作的最终依据#

15.2 遇到异常时保留的信息#

不要连续重复操作。先保留并核对：

• 当前账户和登录邮箱；
• 页面路径和操作时间；
• 充值单号、交易哈希、邀请 ID、开卡编号、卡片 ID、充值申请 ID 或 Delivery ID；
• 初始状态、当前状态和完整失败原因；
• 是否已经出现余额、账本或卡片状态变化。

资金、开卡和卡片充值只有在终态明确后才能决定是否重试。状态仍为处理中时，重复提交可能形成重复业务。