Tài khoản ảo (VA) cho mỗi đơn hàng hoặc mỗi khách một số tài khoản riêng dưới tài khoản ngân hàng của bạn. Khách chuyển vào số VA, SePay biết ngay giao dịch thuộc về đâu và trả VA đó ở trường subAccount của webhook. Đọc thêm về các loại VA và ngân hàng hỗ trợ ở Tài khoản ngân hàng; cách khớp đơn bằng nội dung chuyển khoản có ở Mã thanh toán.
va list và va get chạy trên cả sandbox và production, cần scope read. va issue và va revoke chỉ chạy trên sandbox. Bạn cần đăng nhập.
Mỗi VA nằm dưới một tài khoản ngân hàng, nên các lệnh va nhận xid tài khoản đó qua --bank-account (<bank-account-xid>, cột ID của sepay bank-account list). Chạy trong terminal mà bỏ trống --bank-account thì CLI hiện danh sách để bạn chọn; trong script thì bắt buộc.
Lệnh
| Lệnh | Mô tả | Môi trường |
|---|---|---|
va issue | Cấp VA cố định | Sandbox |
va list | Liệt kê VA của một tài khoản | Cả hai |
va get | Xem một VA | Cả hai |
va revoke | Thu hồi VA | Sandbox |
Trên production, VA được tạo qua API VA theo đơn hàng hoặc trên my.sepay.vn, và thu hồi trên my.sepay.vn.
va issue
Cấp một VA cố định dưới tài khoản ngân hàng.
Tham số
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--bank-account | string | Trong script | Xid tài khoản ngân hàng sẽ chứa VA |
--label | string | Không | Nhãn để nhận ra VA, ví dụ mã đơn DH1709 |
--tid | string | Không | Terminal Vietcombank OneQR đã có |
--terminal-name | string | Không | Tên terminal Vietcombank OneQR mới; không truyền --tid thì CLI tạo terminal mới với tên này |
Ví dụ
$ sepay va issue --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98 --label DH1709env: sandboxIssued virtual account SPVA01709.FIELD VALUEID 7b3d90c4-xxxx-xxxx-xxxx-fa163e2f7c98VA SPVA01709Holder Nguyễn Văn ALabel DH1709Official yesStatic yesActive yesBank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98Created 2026-11-04 10:15:02Updated 2026-11-04 10:15:02VA (ở đây SPVA01709) là số tài khoản khách chuyển tiền vào. ID là xid của VA, dùng cho va get và va revoke.
Loại VA (chính thức hay nội dung) do cấu hình của tài khoản ngân hàng quyết định, không chọn lúc tạo. Chạy lại lệnh sau khi mất kết nối không cấp trùng VA; trong script, truyền --idempotency-key như ở Idempotency.
va list
Liệt kê VA dưới một tài khoản ngân hàng. Viết tắt: va ls.
| Flag | Kiểu | Mô tả |
|---|---|---|
--bank-account | string | Xid tài khoản ngân hàng |
--search | string | Tìm theo số VA hoặc nhãn |
--active | string | 0 | 1 |
--official | string | 0 | 1: VA chính thức / VA nội dung |
--static | string | 0 | 1: VA cố định / VA động |
--created-at-sort | string | asc | desc: sắp theo ngày tạo |
--page, --per-page | int | Phân trang; tối đa 100 |
$ sepay va list --bank-account <bank-account-xid>ID VA HOLDER LABEL OFFICIAL STATIC ACTIVEe3f1a8b2-xxxx-xxxx-xxxx-fa163e2f7c98 SPVA00012 Nguyễn Văn A DH00012 yes yes yespage 1/1 · 1 of 1Cột ID là <va-xid> mà va get và va revoke nhận.
va get
Xem chi tiết một VA.
$ sepay va get 7b3d90c4-xxxx-xxxx-xxxx-fa163e2f7c98 --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98env: sandboxFIELD VALUEID 7b3d90c4-xxxx-xxxx-xxxx-fa163e2f7c98VA SPVA01709Holder Nguyễn Văn ALabel DH1709Official yesStatic yesActive yesBank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98Created 2026-11-04 10:15:02Updated 2026-11-04 10:15:02| Trường | Ý nghĩa |
|---|---|
VA | Số VA, khách chuyển tiền vào số này |
Holder | Tên chủ VA hiện trên app ngân hàng của khách |
Label | Nhãn bạn đặt lúc cấp, ví dụ mã đơn |
Official | yes: VA chính thức do ngân hàng cấp số. no: VA nội dung, khớp theo nội dung chuyển khoản |
Static | yes: VA cố định, nhận tiền nhiều lần. no: VA động |
Active | no khi VA đã bị thu hồi hoặc tắt |
va revoke
Thu hồi một VA. Lệnh nhận xid hoặc số VA, và luôn hỏi xác nhận; chạy trong script thì thêm --yes.
$ sepay va revoke SPVA01709 --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98env: sandbox? revoke virtual account SPVA01709? › YesRevoked virtual account SPVA01709.Không có lệnh nào khôi phục VA đã thu hồi. Kiểm tra kỹ xid trước khi chạy va revoke; cần dùng lại thì cấp VA mới bằng va issue.
Thử VA trên sandbox
Mở webhook listen để xem subAccount của webhook, rồi tạo giao dịch tiền vào số VA đã cấp bằng sandbox simulate:
$ sepay sandbox simulate va_credit --bank-account <bank-account-xid> --va <số VA> --amount 50000--va nhận số VA (cột VA của va list), không phải xid. Tra lại giao dịch theo VA bằng sepay transaction list --va-xid <va-xid>.
Thông báo lỗi
| Thông báo hoặc hiện tượng | Nguyên nhân |
|---|---|
va issue is sandbox-only; drop --env production (hoặc va revoke ...) | Hai lệnh chỉ chạy trên sandbox; VA production tạo qua API hoặc my.sepay.vn |
subAccount trống trong webhook | Giao dịch không vào số VA, hoặc webhook không nhận VA của tài khoản đó; xem cấu hình VA của webhook bằng sepay webhook get <xid> (Chọn tài khoản nhận thông báo) |