銀行轉帳（越南）

**管理員位置：**Finance › Payment channels › VN bank transfer（/payments/bank）。匯率：Finance › Payment channels › Exchange rates（/payments/fx）。

功能

允許客戶透過越南盾的一般銀行轉帳來為 USD 錢包加值。NexCMP 會顯示 VietQR 代碼、帳戶詳細資訊以及唯一的轉帳備忘錄；Sepay 會監控您的銀行帳戶並在款項到達時呼叫 Webhook，隨後 NexCMP 便會將款項存入錢包。若您的客戶位於越南，請使用此功能。

僅顯示於越南語介面

越南銀行選項僅在入口網站以Vietnamese顯示時才會提供給客戶。使用任何其他語言的客戶永遠不會看到它。

需求

項目	需求
銀行帳戶	連線至 my.sepay.vn 之 Sepay 帳戶的越南銀行帳戶（或 Sepay 虛擬帳戶，VA）。
Sepay	已啟用 webhook 整合功能的 Sepay 帳戶。
匯率	必須存在 USD 對 VND 的匯率：請先至 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 帳戶使用付款代碼結構，請在那裡註冊相同的前綴以便 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 中填入：

   欄位	範例	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。

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

驗證

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 transfers

進入帳戶但沒有帶有效備註的款項會顯示在頁面底部的 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	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"	已達到待處理訂單上限	請完成或等待其過期。