---
title: 銀行轉帳（越南）
description: 接受越南銀行轉帳（VND）搭配 Sepay — 收款帳戶、備忘錄前綴、Webhook、限額以及如何指派未匹配的轉帳。
url: https://nexcmp.com/zh-tw/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 僅顯示於越南語介面
越南銀行選項僅在入口網站以**Vietnamese**顯示時才會提供給客戶。使用任何其他語言的客戶永遠不會看到它。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 銀行帳戶 | 連線至 [my.sepay.vn](https://my.sepay.vn) 之 Sepay 帳戶的越南銀行帳戶（或 Sepay 虛擬帳戶，**VA**）。 |
| Sepay | 已啟用 webhook 整合功能的 Sepay 帳戶。 |
| 匯率 | 必須存在 USD 對 VND 的匯率：請先至 **Exchange rates** 更新。若無匯率，通道將回應 `fx_unavailable` 且客戶無法發起轉帳。 |
| 網路 | 您的面板必須透過 HTTPS 存取，以便 Sepay 可以呼叫 `https://<your-domain>/v1/billing/sepay/webhook`。 |
| 相依項目 | [貨幣與匯率](https://nexcmp.com/zh-tw/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 帳戶使用*付款代碼結構*，請在那裡註冊相同的前綴以便 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** 中填入：

   | 欄位 | 範例 | Rule |
   |---|---|---|
   | 銀行 | `VCB` Vietcombank | 從清單中選擇；BIN 會自動填入。 |
   | 帳號 | `0123456789` | 4–24 個數字或大寫字母。 |
   | 虛擬帳戶（VA — 選填） | | 若設定，客戶將轉帳至 VA 且 QR Code 會顯示它。 |
   | 戶名 | `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**。

![填入範例值的 VN bank transfer 頁面，包含收款帳戶、備註前綴與 webhook 驗證](https://nexcmp.com/zh-tw/docs/images/billing/bank-transfer-vn-01-config.webp)

![已開啟 Sepay 開關與預設限制的 Channel and limits 卡片](https://nexcmp.com/zh-tw/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** 中設定的利潤率與捨入步驟）將 USD 金額進行換算，並將 **VND 金額向上捨入**至捨入級距。
3. 客戶會看到一個包含帳號、銀行、金額與備註的 QR 碼（VietQR，於本地產生）。
4. 轉帳完成後，Sepay 會呼叫 webhook，NexCMP 會將 `floor(VND received × 100 / rate)` 美分入帳。匯率在建立訂單時即已鎖定；若款項在訂單過期後才到達，將會採用鎖定匯率與當下匯率中較高者。
5. 訂單會在 **Order expiry** 後過期；對帳作業每 **Reconcile every** 分鐘執行一次作為安全網（需要 userapi token）。

## 驗證 {#verify}

1. 以客戶身分在越南語介面上建立測試訂單。檢查金額、帳號與備註是否正確。
2. 以正確的備註轉帳允許的最低金額。
3. 在一分鐘內，入口網站會顯示存款已完成且錢包餘額增加；銀行頁面上的 **State** 卡片會顯示最後的 webhook 時間。
4. 開啟 **Finance › Billing › Top-ups** 並檢查付款是否已列出收到的 VND 金額。

## 限制與注意事項 {#limits-notes}

- **最低金額。** 客戶看到的 VND 最低金額為 **Min / order** 與 [minimum top-up](https://nexcmp.com/zh-tw/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-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` | Prefix invalid | 使用 2–5 個大寫字母且不含 `ORD`。 |
| `account_name` error | Accents or lowercase | 使用未帶變音符號的大寫字母、數字、空格、點或連字號。 |
| `webhook_secret: 8–200 characters` | Key too short | 使用至少 8 個可列印字元。 |
| 客戶無法看到此選項 | 不在越南文介面、已關閉或無費率 | 請檢查語言、開關與費率。 |
| 客戶已付款但未入帳 | Webhook未送達、備註已更改、金額錯誤 | 請檢查Sepay的Webhook記錄；若備註錯誤，轉帳將會位於**Unmatched transactions**中。 |
| Webhook傳回401或403 | 驗證方法或金鑰不符 | 請在Sepay與NexCMP中使用相同的方法與金鑰。 |
| 客戶看到 "Too many pending requests" | 已達到待處理訂單上限 | 請完成或等待其過期。 |