A virtual account (VA) gives each order or customer its own account number under your bank account. The customer pays into the VA number, SePay knows right away which order the transaction belongs to, and returns that VA in the webhook's subAccount field. VA types and supported banks are covered in Bank accounts; matching orders by transfer content is in Payment codes.
va list and va get run on both sandbox and production and need the read scope. va issue and va revoke run on the sandbox only. You need to be signed in.
Each VA belongs to a bank account, so the va commands take that account's xid through --bank-account (<bank-account-xid>, the ID column of sepay bank-account list). In a terminal, leaving out --bank-account lets you pick an account; in a script it is required.
Commands
| Command | Description | Environment |
|---|---|---|
va issue | Issue a static VA | Sandbox |
va list | List an account's VAs | Both |
va get | Show one VA | Both |
va revoke | Revoke a VA | Sandbox |
On production, VAs are created through the order VA API or in my.sepay.vn, and revoked in my.sepay.vn.
va issue
Issues a static VA under a bank account.
Parameters
| Flag | Type | Required | Description |
|---|---|---|---|
--bank-account | string | In a script | Xid of the bank account the VA goes under |
--label | string | No | Label to recognize the VA by, such as the order code DH1709 |
--tid | string | No | Existing Vietcombank OneQR terminal |
--terminal-name | string | No | Name of a new Vietcombank OneQR terminal; without --tid the CLI creates a terminal with this name |
Example
$ sepay va issue --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98 --label DH1709env: sandboxIssued virtual account SPVA01709.FIELD VALUEID 7b3d90c4-xxxx-xxxx-xxxx-fa163e2f7c98VA SPVA01709Holder Nguyen Van ALabel DH1709Official yesStatic yesActive yesBank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98Created 2026-11-04 10:15:02Updated 2026-11-04 10:15:02VA (here SPVA01709) is the account number the customer pays into. ID is the VA's xid, which va get and va revoke take.
Whether the VA is official or content-based follows the bank account's setup; you don't choose it when issuing. Running the command again after a dropped connection never issues the VA twice; in a script, pass --idempotency-key as shown in Idempotency.
va list
Lists the VAs under a bank account. Alias: va ls.
| Flag | Type | Description |
|---|---|---|
--bank-account | string | Bank account xid |
--search | string | Search by VA number or label |
--active | string | 0 | 1 |
--official | string | 0 | 1: official VA / content-based VA |
--static | string | 0 | 1: static VA / dynamic VA |
--created-at-sort | string | asc | desc: sort by creation date |
--page, --per-page | int | Pagination; at most 100 |
$ sepay va list --bank-account <bank-account-xid>ID VA HOLDER LABEL OFFICIAL STATIC ACTIVEe3f1a8b2-xxxx-xxxx-xxxx-fa163e2f7c98 SPVA00012 Nguyen Van A DH00012 yes yes yespage 1/1 · 1 of 1The ID column is the <va-xid> that va get and va revoke take.
va get
Shows one VA's details.
$ sepay va get 7b3d90c4-xxxx-xxxx-xxxx-fa163e2f7c98 --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98env: sandboxFIELD VALUEID 7b3d90c4-xxxx-xxxx-xxxx-fa163e2f7c98VA SPVA01709Holder Nguyen Van ALabel DH1709Official yesStatic yesActive yesBank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98Created 2026-11-04 10:15:02Updated 2026-11-04 10:15:02| Field | Meaning |
|---|---|
VA | The VA number the customer pays into |
Holder | Holder name shown in the customer's banking app |
Label | The label you set when issuing, such as an order code |
Official | yes: an official VA with a number issued by the bank. no: a content-based VA, matched by transfer content |
Static | yes: a static VA that takes payments more than once. no: a dynamic VA |
Active | no once the VA has been revoked or turned off |
va revoke
Revokes a VA. The command takes the xid or the VA number, and always asks for confirmation; in a script, add --yes.
$ sepay va revoke SPVA01709 --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98env: sandbox? revoke virtual account SPVA01709? › YesRevoked virtual account SPVA01709.No command restores a revoked VA. Double-check the xid before running va revoke; if you need it again, issue a new VA with va issue.
Test a VA in the sandbox
Open webhook listen to see the webhook's subAccount, then create an incoming payment to the VA number with sandbox simulate:
$ sepay sandbox simulate va_credit --bank-account <bank-account-xid> --va <VA number> --amount 50000--va takes the VA number (the VA column of va list), not the xid. Look the transaction up by VA with sepay transaction list --va-xid <va-xid>.
Error messages
| Message or symptom | Cause |
|---|---|
va issue is sandbox-only; drop --env production (or va revoke ...) | These two commands run on the sandbox only; production VAs are created through the API or in my.sepay.vn |
subAccount is empty in the webhook | The transaction didn't go to a VA number, or the webhook doesn't take that account's VAs; check the webhook's VA config with sepay webhook get <xid> (Choose what each account notifies) |