Chuyển khoản ngân hàng (Việt Nam)

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

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 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.

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

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.
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á.

Chuẩn bị hạ tầng

Về phía Sepay:

1. Trong 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

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.

Bảo mật webhook

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

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

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 ý

• 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.
• Đơ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

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ố

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.