银行转账（越南）

管理后台位置： Finance › Payment channels › VN bank transfer (/payments/bank)。汇率：Finance › Payment channels › Exchange rates (/payments/fx)。

功能说明

允许客户通过越南盾的普通银行转账来充值 USD 钱包。NexCMP 会显示一个 VietQR 码、账户详情以及一个唯一的转账附言；Sepay 会监视您的银行账户并在资金到达时调用 webhook，随后 NexCMP 会将款项记入钱包。如果您面向越南客户开展业务，请使用此功能。

仅在越南语界面中显示

VN 银行选项仅在门户语言显示为 Vietnamese 时向客户提供。使用任何其他语言的客户都不会看到该选项。

前提条件

项目	要求
银行账户	连接至 my.sepay.vn 上的 Sepay 账户的越南银行账户（或 Sepay 虚拟账户，VA）。
Sepay	已启用 Webhook 集成的 Sepay 账户。
汇率	必须存在美元兑越南盾汇率：请先在 Exchange rates 下更新。若无汇率，渠道将响应 fx_unavailable，且客户无法发起转账。
网络	您的面板必须可通过 HTTPS 访问，以便 Sepay 能够调用 https://<your-domain>/v1/billing/sepay/webhook。
依赖项	货币与汇率。

准备基础设施

在 Sepay 端：

1. 在 my.sepay.vn 中连接您的银行账户（或创建 VA）并确保交易显示。
2. 决定备注前缀 — 2 至 5 个大写字母，例如 PAY。NexCMP 生成的备注为该前缀后跟 8 位随机数字（例如 PAY48210937）。前缀不得包含 ORD，且不应被任何其他向同一账户收款的系统使用。
3. 如果您的 Sepay account 使用了支付代码结构，请在那里注册相同的前缀以便 Sepay 识别备注。
4. 在 NexCMP 页面提供 URL 和密钥（下方第 7 步）后，再创建 Webhook。

在NexCMP中连接

1. 打开 Finance › Payment channels › Exchange rates，如果尚未存储汇率，请点击 Update exchange rates。

2. 打开 Finance › Payment channels › VN bank transfer（/payments/bank）。

3. 在 Receiving account 中填写：

   字段	示例	规则
   银行	VCB Vietcombank	从列表中选择；BIN 会自动填充。
   账号	0123456789	4–24位数字或大写字母。
   虚拟账户（VA — 可选）		若设置，客户将转账至该 VA 且二维码会显示它。
   户名	NGUYEN VAN A	无变音符号，大写，2–60个字符。
   转账备注前缀	PAY	2–5个大写字母，无 ORD。

4. 在 Webhook authentication 中选择 Auth method：HMAC-SHA256（推荐）或 API key，并输入 Webhook key / HMAC secret（8–200个字符）。可选输入来自 Sepay 的 userapi token；它仅用于对账 Webhook 丢失的转账。

5. 在 Channel & limits 中设置限制（括号内为默认值）：Min / order（10,000 VND）、Max / order（200,000,000 VND）、Order expiry（120分钟，15–1440）、Max pending orders / account（3，1–10）、Reconcile every（10分钟），以及可选的 Allowed webhook IPs（逗号分隔；留空表示仅记录 IP）。

6. 点击 Save。一旦账户、姓名、前缀和密钥有效，红色的“Sepay not configured”横幅便会消失。

7. 复制Webhook URL to paste into my.sepay.vn（显示为https://<your-domain>/v1/billing/sepay/webhook），点击Copy。在SePay中打开webhook集成，粘贴该URL，选择相同的身份验证类型和密钥，并启用“money in”事件。

8. 点击 Test connection。然后开启 Enable Sepay for clients (main site) 并点击 Save。

Webhook 安全性

方法	Sepay 必须发送的内容
HMAC-SHA256	Header X-SePay-Signature: sha256=<hex>，基于 "<X-SePay-Timestamp>.<raw body>" 计算；时间戳误差最多不超过 300 秒。
API密钥	Header Authorization: Apikey <key>。

仅检查请求头（从不检查请求体或查询字符串），且比对过程采用恒定时间算法。仅使用转入您配置的账户或虚拟账户（VA）的入账（transferType = in）。每笔 Sepay 交易仅存储一次，因此重试的 Webhook 绝不会重复入账。即使 NexCMP 故意忽略某笔交易，也会响应 200 {"success":true}，并且仅对临时错误返回 HTTP 5xx 以便 Sepay 重试。

客户如何付款

1. 在 Billing › Deposit（越南语界面）中，客户选择越南银行转账选项和金额，然后点击创建转账按钮。
2. NexCMP 按照存储的汇率（包含您在 Exchange rates 中设置的加价幅度和舍入步长）换算美元金额，并将 VND 金额向上舍入 到指定的舍入步长。
3. 客户将看到一个本地生成的二维码（VietQR），其中包含账号、银行、金额和备注信息。
4. 转账完成后，Sepay 调用 Webhook，NexCMP 为 floor(VND received × 100 / rate) 分钟入账。汇率在订单创建时锁定；如果资金在订单过期后到达，则取锁定汇率与当前汇率中的较高者。
5. 订单在 Order expiry 后过期；对账作为安全网每隔 Reconcile every 分钟运行一次（需要 userapi 令牌）。

验证

1. 在越南语界面上以客户身份创建一个测试订单。检查金额、账户和备注是否正确。
2. 转账允许的最小金额并附带准确的备注。
3. 一分钟内，门户网站将显示存款已完成，且钱包余额增加；银行页面上的 State 卡片会显示最近一次 Webhook 的时间。
4. 打开 Finance › Billing › Top-ups 并检查该笔支付是否已列出以及收到的 VND 金额是否正确。

限制与注意事项

• 最低金额。 客户看到的 VND 最低金额为 Min / order 与 minimum top-up 的 VND 等值金额中的较大者。
• 待处理订单。 每个客户最多只能有 Max pending orders / account 个未完成订单（默认值为 3）。
• 相同备注两次。 使用相同备注转账两次会按当前汇率产生第二笔已完成的支付。
• 不自动退款 到银行账户。
• 手续费。 该通道在 Fees & limits 中没有固定手续费行；汇率加价是唯一的调整项。
• Resellers 可以配置他们自己的账户；其 Webhook URL 以 /v1/billing/sepay/webhook/r/<id> 结尾。

未匹配的转账

已到达账户但没有携带有效备注的资金会显示在页面底部的 Unmatched transactions 中（可过滤 All channel owners 或 Master）。与客户核对银行参考号，然后点击 Assign 并选择对应的账户。钱包将按当前汇率入账。

故障排查

症状	原因	解决办法
横幅“Sepay not configured”	银行、账户、户名、前缀或密钥丢失或无效	完成 Receiving account 和 Webhook authentication 卡片。
横幅“USD/VND rate blocked”（fx_unavailable）	未存储汇率	前往Exchange rates › Update exchange rates。
prefix: 2–5 capital letters, no ORD	前缀无效	使用 2–5 个大写字母，且不包含 ORD。
account_name 错误	包含变音符号或小写字母	使用无变音符号的大写字母、数字、空格、点或连字符。
webhook_secret: 8–200 characters	密钥过短	请使用至少 8 个可打印字符。
客户无法看到该选项	不在越南语界面、未启用或无汇率	检查语言、开关和汇率。
客户已付款但未入账	Webhook未到达、备注被篡改、金额错误	检查Sepay的Webhook日志；如果备注错误，转账将显示在Unmatched transactions中。
Webhook返回401或403	认证方法或密钥不匹配	在Sepay和NexCMP中使用相同的方法和密钥。
客户看到“Too many pending requests”	已达到待处理订单上限	等待订单完成或过期。