---
title: 银行转账（越南）
description: 通过 SePay 接受越南盾（VND）银行转账——接收账户、附言前缀、Webhook、限额以及如何分配未匹配的转账。
url: https://nexcmp.com/zh-cn/docs/billing/bank-transfer-vn/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 银行转账（越南） {#bank-transfer-vietnam}

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

## 功能说明 {#what-it-does}

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

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

## 前提条件 {#requirements}

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

## 准备基础设施 {#prepare-the-infrastructure}

在 Sepay 端：

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

## 在NexCMP中连接 {#connect-in-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 认证的越南银行转账页面](https://nexcmp.com/zh-cn/docs/images/billing/bank-transfer-vn-01-config.webp)

![启用了 Sepay 开关并带有默认限制的通道和限制卡片](https://nexcmp.com/zh-cn/docs/images/billing/bank-transfer-vn-02-limits.webp)

### Webhook 安全性 {#webhook-security}

| 方法 | 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 重试。

## 客户如何付款 {#how-the-customer-pays}

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 令牌）。

## 验证 {#verify}

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

## 限制与注意事项 {#limits-notes}

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

### 未匹配的转账 {#unmatched-transfers}

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

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| 横幅“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” | 已达到待处理订单上限 | 等待订单完成或过期。 |