---
title: Chuyển khoản ngân hàng (Việt Nam)
description: Nhận chuyển khoản ngân hàng Việt Nam (VND) qua SePay — tài khoản nhận, tiền tố memo, webhook, hạn mức và cách gán chuyển khoản không khớp.
url: https://nexcmp.com/vi/docs/billing/bank-transfer-vn/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Chuyển khoản ngân hàng (Việt Nam) {#bank-transfer-vietnam}

> **Vị trí trong trang quản trị:** Finance › Payment channels › VN bank transfer (`/payments/bank`). Tỷ giá: Finance › Payment channels › Exchange rates (`/payments/fx`).

## Chức năng {#what-it-does}

Cho phép khách hàng nạp tiền vào ví USD bằng hình thức chuyển khoản ngân hàng thông thường bằng đồng Việt Nam. NexCMP hiển thị mã VietQR, thông tin tài khoản và **transfer memo** duy nhất; [Sepay](https://sepay.vn) theo dõi tài khoản ngân hàng của bạn và gọi webhook khi có tiền vào, rồi NexCMP sẽ cộng tiền vào ví. Hãy sử dụng phương thức này nếu bạn bán dịch vụ cho khách hàng tại Việt Nam.

::: info Chỉ hiển thị trong giao diện tiếng Việt
Tùy chọn ngân hàng VN chỉ hiển thị cho khách hàng khi portal đang ở ngôn ngữ **Vietnamese**. Khách hàng sử dụng bất kỳ ngôn ngữ nào khác sẽ không bao giờ nhìn thấy tùy chọn này.
:::

## Yêu cầu {#requirements}

| Hạng mục | Yêu cầu |
|---|---|
| Tài khoản ngân hàng | Một tài khoản ngân hàng Việt Nam (hoặc tài khoản ảo Sepay, **VA**) được kết nối với tài khoản Sepay tại [my.sepay.vn](https://my.sepay.vn). |
| Sepay | Tài khoản Sepay đã bật tính năng tích hợp webhook. |
| Tỷ giá hối đoái | Cần phải có tỷ giá USD sang VND: hãy cập nhật tỷ giá này trong **Exchange rates** trước. Nếu không có tỷ giá, kênh thanh toán sẽ phản hồi `fx_unavailable` và khách hàng không thể bắt đầu giao dịch chuyển khoản. |
| Mạng | Bảng điều khiển của bạn phải truy cập được qua HTTPS để Sepay có thể gọi `https://<your-domain>/v1/billing/sepay/webhook`. |
| Thành phần phụ thuộc | [Tiền tệ và tỷ giá](https://nexcmp.com/vi/docs/catalog/currency-and-exchange-rates/). |

## Chuẩn bị hạ tầng {#prepare-the-infrastructure}

Về phía Sepay:

1. Trong [my.sepay.vn](https://my.sepay.vn), hãy kết nối tài khoản ngân hàng của bạn (hoặc tạo VA) và đảm bảo các giao dịch hiển thị bình thường.
2. Quyết định **memo prefix** — 2 đến 5 chữ cái viết hoa, ví dụ `PAY`. NexCMP sẽ tạo memo gồm tiền tố này theo sau là 8 chữ số ngẫu nhiên (ví dụ `PAY48210937`). Tiền tố không được chứa `ORD` và không nên được dùng bởi bất kỳ hệ thống nào khác nhận tiền vào cùng tài khoản đó.
3. Nếu tài khoản Sepay của bạn sử dụng *cấu trúc mã thanh toán*, hãy đăng ký cùng tiền tố đó tại Sepay để hệ thống nhận diện được memo.
4. Hãy tạo webhook sau, khi trang NexCMP đã cung cấp cho bạn URL và key (bước 7 bên dưới).

## Kết nối trong NexCMP {#connect-in-nexcmp}

1. Mở **Finance › Payment channels › Exchange rates** và nhấp vào **Update exchange rates** nếu chưa có tỷ giá nào được lưu.
2. Mở **Finance › Payment channels › VN bank transfer** (`/payments/bank`).
3. Trong **Receiving account**, hãy điền:

   | Trường | Ví dụ | Quy tắc |
   |---|---|---|
   | Ngân hàng | `VCB` Vietcombank | Chọn từ danh sách; mã BIN sẽ tự động điền. |
   | Số tài khoản | `0123456789` | 4–24 chữ số hoặc chữ cái viết hoa. |
   | Tài khoản ảo (VA — tùy chọn) | | Nếu được thiết lập, khách hàng sẽ chuyển khoản tới VA và mã QR sẽ hiển thị thông tin này. |
   | Tên chủ tài khoản | `NGUYEN VAN A` | Không dấu, VIẾT HOA, 2–60 ký tự. |
   | Tiền tố memo chuyển khoản | `PAY` | 2–5 chữ cái viết hoa, không có `ORD`. |

4. Trong **Webhook authentication**, chọn **Auth method**: **HMAC-SHA256** (khuyên dùng) hoặc **API key**, rồi nhập **Webhook key / HMAC secret** (8–200 ký tự). Bạn có thể tùy chọn nhập **userapi token** từ Sepay; token này chỉ dùng để đối soát các giao dịch chuyển khoản bị mất webhook.
5. Trong **Channel & limits**, hãy thiết lập các giới hạn (giá trị mặc định trong ngoặc đơn): **Min / order** (10,000 VND), **Max / order** (200,000,000 VND), **Order expiry** (120 phút, 15–1440), **Max pending orders / account** (3, 1–10), **Reconcile every** (10 phút) và tùy chọn **Allowed webhook IPs** (phân tách bằng dấu phẩy; để trống nghĩa là IP chỉ được ghi log).
6. Nhấp vào **Save**. Banner màu đỏ "Sepay not configured" sẽ biến mất sau khi số tài khoản, tên, tiền tố và key hợp lệ.
7. Sao chép **Webhook URL to paste into my.sepay.vn** (có dạng `https://<your-domain>/v1/billing/sepay/webhook`) bằng **Copy**. Trong Sepay, mở tích hợp webhook, dán URL, chọn cùng loại xác thực và key, rồi bật sự kiện "money in".
8. Nhấp vào **Test connection**. Sau đó bật **Enable Sepay for clients (main site)** và chọn **Save**.

![Trang chuyển khoản ngân hàng Việt Nam với tài khoản nhận tiền, tiền tố memo và xác thực webhook được điền bằng các giá trị mẫu](https://nexcmp.com/vi/docs/images/billing/bank-transfer-vn-01-config.webp)

![Thẻ Channel and limits với công tắc Sepay được bật và các hạn mức mặc định](https://nexcmp.com/vi/docs/images/billing/bank-transfer-vn-02-limits.webp)

### Bảo mật webhook {#webhook-security}

| Phương thức | Dữ liệu Sepay phải gửi |
|---|---|
| HMAC-SHA256 | Header `X-SePay-Signature: sha256=<hex>`, được tính trên `"<X-SePay-Timestamp>.<raw body>"`; timestamp có thể chênh lệch tối đa 300 giây. |
| API key | Header `Authorization: Apikey <key>`. |

Chỉ các header được kiểm tra (không bao giờ kiểm tra body hoặc query string) và phép so sánh diễn ra theo thời gian không đổi (constant-time). Chỉ các giao dịch chuyển tiền đến (`transferType = in`) vào tài khoản hoặc VA đã cấu hình của bạn mới được sử dụng. Mỗi giao dịch Sepay chỉ được lưu một lần, vì vậy webhook gửi lại sẽ không bao giờ cộng tiền hai lần. NexCMP phản hồi `200 {"success":true}` ngay cả khi chủ động bỏ qua một giao dịch, và chỉ trả về HTTP 5xx đối với các lỗi tạm thời để Sepay thử lại.

## Cách khách hàng thanh toán {#how-the-customer-pays}

1. Trong **Billing › Deposit** (giao diện tiếng Việt), khách hàng chọn tùy chọn chuyển khoản ngân hàng Việt Nam và số tiền, sau đó nhấp vào nút tạo giao dịch.
2. NexCMP quy đổi số tiền USD theo tỷ giá đã lưu (bao gồm biên độ và bước làm tròn bạn thiết lập trong **Exchange rates**) và **làm tròn tăng số tiền VND** theo bước làm tròn.
3. Khách hàng nhìn thấy mã QR (VietQR, được tạo cục bộ) kèm số tài khoản, ngân hàng, số tiền và memo.
4. Sau khi chuyển khoản, Sepay gọi webhook, NexCMP cộng `floor(VND received × 100 / rate)` cent. Tỷ giá được khóa khi đơn hàng được tạo; nếu tiền đến sau khi đơn hàng đã hết hạn, tỷ giá cao hơn giữa tỷ giá đã khóa và tỷ giá hiện tại sẽ được áp dụng.
5. Đơn hàng hết hạn sau **Order expiry**; quy trình đối soát chạy mỗi **Reconcile every** phút như một lớp bảo vệ dự phòng (cần userapi token).

## Kiểm tra {#verify}

1. Tạo một đơn hàng thử nghiệm dưới vai trò khách hàng trên giao diện tiếng Việt. Kiểm tra xem số tiền, tài khoản và memo đã chính xác chưa.
2. Chuyển số tiền tối thiểu được phép với chính xác memo.
3. Trong vòng một phút, cổng thông tin sẽ hiển thị khoản nạp đã hoàn tất và số dư ví tăng lên; thẻ **State** trên trang ngân hàng hiển thị thời gian webhook gần nhất.
4. Mở **Finance › Billing › Top-ups** và kiểm tra xem khoản thanh toán có được liệt kê cùng số tiền VND đã nhận hay không.

## Hạn mức & lưu ý {#limits-notes}

- **Tối thiểu.** Mức VND tối thiểu mà khách hàng thấy là giá trị lớn hơn giữa **Min / order** và giá trị VND của [mức nạp tối thiểu](https://nexcmp.com/vi/docs/billing/minimum-top-up/).
- **Đơn hàng chờ xử lý.** Khách hàng chỉ có thể có tối đa **Max pending orders / account** đơn hàng đang mở (mặc định là 3).
- **Trùng memo hai lần.** Chuyển tiền hai lần với cùng một memo sẽ tạo khoản thanh toán hoàn tất thứ hai theo tỷ giá hiện tại.
- **Không hoàn tiền tự động** về tài khoản ngân hàng.
- **Phí.** Kênh này không có dòng phí cố định trong **Fees & limits**; biên độ tỷ giá là khoản điều chỉnh duy nhất.
- **Resellers** có thể định cấu hình tài khoản của riêng họ; URL webhook của họ kết thúc bằng `/v1/billing/sepay/webhook/r/<id>`.

### Giao dịch chuyển tiền chưa khớp {#unmatched-transfers}

Tiền đã vào tài khoản nhưng không có memo hợp lệ sẽ xuất hiện trong **Unmatched transactions** ở cuối trang (lọc theo *All channel owners* hoặc *Master*). Kiểm tra mã tham chiếu ngân hàng với khách hàng, sau đó nhấp vào **Assign** và chọn tài khoản. Ví sẽ được cộng tiền theo tỷ giá hiện tại.

## Xử lý sự cố {#troubleshooting}

| Hiện tượng | Nguyên nhân | Cách khắc phục |
|---|---|---|
| Banner thông báo "Sepay not configured" | Thiếu hoặc không hợp lệ thông tin ngân hàng, tài khoản, tên chủ tài khoản, tiền tố hoặc khóa | Hoàn tất các thẻ **Receiving account** và **Webhook authentication**. |
| Banner thông báo "USD/VND rate blocked" (`fx_unavailable`) | Không có tỷ giá nào được lưu | Chọn **Exchange rates › Update exchange rates**. |
| `prefix: 2–5 capital letters, no ORD` | Tiền tố không hợp lệ | Sử dụng 2–5 chữ cái in hoa không có `ORD`. |
| Lỗi `account_name` | Có dấu hoặc chữ thường | Sử dụng chữ in HOA không dấu, chữ số, dấu cách, dấu chấm hoặc dấu gạch nối. |
| `webhook_secret: 8–200 characters` | Khóa quá ngắn | Sử dụng ít nhất 8 ký tự in được. |
| Khách hàng không thấy tùy chọn | Không ở giao diện tiếng Việt, công tắc đang tắt, hoặc chưa có tỷ giá | Kiểm tra ngôn ngữ, công tắc và tỷ giá. |
| Khách hàng đã thanh toán nhưng không được cộng tiền | Webhook không tới, nội dung chuyển khoản bị đổi, sai số tiền | Kiểm tra webhook log của SePay; giao dịch chuyển khoản sẽ nằm trong **Unmatched transactions** nếu nội dung chuyển khoản bị sai. |
| Webhook trả về 401 hoặc 403 | Phương thức xác thực hoặc khóa không khớp | Sử dụng cùng phương thức và khóa trong SePay và NexCMP. |
| Khách hàng thấy "Too many pending requests" | Đã đạt giới hạn đơn hàng đang chờ xử lý | Chờ khách hoàn tất hoặc chờ đơn hết hạn. |