Virtual accounts (VA) in SePay CLI

Issue, list and revoke virtual accounts (VA) with SePay CLI so each order gets its own account number, then test a payment to a VA in the sandbox.

||

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

CommandDescriptionEnvironment
va issueIssue a static VASandbox
va listList an account's VAsBoth
va getShow one VABoth
va revokeRevoke a VASandbox

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

FlagTypeRequiredDescription
--bank-accountstringIn a scriptXid of the bank account the VA goes under
--labelstringNoLabel to recognize the VA by, such as the order code DH1709
--tidstringNoExisting Vietcombank OneQR terminal
--terminal-namestringNoName 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:02

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

FlagTypeDescription
--bank-accountstringBank account xid
--searchstringSearch by VA number or label
--activestring0 | 1
--officialstring0 | 1: official VA / content-based VA
--staticstring0 | 1: static VA / dynamic VA
--created-at-sortstringasc | desc: sort by creation date
--page, --per-pageintPagination; 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 1

The 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
FieldMeaning
VAThe VA number the customer pays into
HolderHolder name shown in the customer's banking app
LabelThe label you set when issuing, such as an order code
Officialyes: an official VA with a number issued by the bank. no: a content-based VA, matched by transfer content
Staticyes: a static VA that takes payments more than once. no: a dynamic VA
Activeno 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.
A revoked VA can't be restored

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 symptomCause
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 webhookThe 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)