Tài khoản ảo (VA) trong SePay CLI

Cấp, xem và thu hồi tài khoản ảo (VA) bằng SePay CLI để mỗi đơn hàng có một số tài khoản riêng, rồi thử giao dịch vào VA trên sandbox.

||

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ệnhMô tảMôi trường
va issueCấp VA cố địnhSandbox
va listLiệt kê VA của một tài khoảnCả hai
va getXem một VACả hai
va revokeThu hồi VASandbox

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ố

FlagKiểuBắt buộcMô tả
--bank-accountstringTrong scriptXid tài khoản ngân hàng sẽ chứa VA
--labelstringKhôngNhãn để nhận ra VA, ví dụ mã đơn DH1709
--tidstringKhôngTerminal Vietcombank OneQR đã có
--terminal-namestringKhôngTê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:02

VA (ở đâ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.

FlagKiểuMô tả
--bank-accountstringXid tài khoản ngân hàng
--searchstringTìm theo số VA hoặc nhãn
--activestring0 | 1
--officialstring0 | 1: VA chính thức / VA nội dung
--staticstring0 | 1: VA cố định / VA động
--created-at-sortstringasc | desc: sắp theo ngày tạo
--page, --per-pageintPhâ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 1

Cộ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
VASố VA, khách chuyển tiền vào số này
HolderTên chủ VA hiện trên app ngân hàng của khách
LabelNhãn bạn đặt lúc cấp, ví dụ mã đơn
Officialyes: 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
Staticyes: VA cố định, nhận tiền nhiều lần. no: VA động
Activeno 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.
VA đã thu hồi không lấy lại được

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ượngNguyê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 webhookGiao 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)