Tài khoản ngân hàng trong SePay CLI

Xem tài khoản ngân hàng và lấy xid cho webhook, VA, giả lập giao dịch bằng SePay CLI, đổi nhãn hiển thị, rồi tạo hoặc xóa tài khoản thử trên sandbox.

||

Nhiều lệnh SePay CLI cần xid của tài khoản ngân hàng (<bank-account-xid>), ví dụ webhook create --bank-account, va issue và sandbox simulate. Lấy xid bằng sepay bank-account list (viết tắt sepay ba ls), rồi xem chi tiết hoặc đổi nhãn tài khoản trên cả sandbox lẫn production.

LệnhViệcMôi trường
bank-account listLiệt kê tài khoản, lấy xidCả hai
bank-account getXem một tài khoảnCả hai
bank-account updateĐổi nhãn hiển thịCả hai
bank-account createTạo tài khoản thửSandbox
bank-account deleteXóa tài khoản thửSandbox

Trên production, tài khoản ngân hàng thật được liên kết và hủy liên kết trên my.sepay.vn, xem Thêm tài khoản ngân hàng.

bank-account list

Liệt kê tài khoản ngân hàng của công ty. Cột ID là xid mà các lệnh khác nhận:

$ sepay bank-account listenv: sandboxID                                    BANK  ACCOUNT     HOLDER        LABEL            CONNECTION  ACCUMULATED  ACTIVE832529c1-xxxx-xxxx-xxxx-fa163e2f7c98  ACB   0000000001  NGUYEN VAN A  Cua hang Quan 1  api         0            yesd6719d04-xxxx-xxxx-xxxx-a6006ab65aca  ACB   0000000002  NGUYEN VAN A  Cua hang Quan 3  api         0            yespage 1/1 · 2 of 2
FlagKiểuMô tả
--searchstringTìm theo tên chủ tài khoản, nhãn hoặc số tài khoản
--bankstringLọc theo ngân hàng, ví dụ ACB
--activestring1 chỉ tài khoản đang bật, 0 chỉ tài khoản đã tắt
--page, --per-pageintPhân trang; tối đa 100 dòng mỗi trang

Cột CONNECTION cho biết tài khoản kết nối với SePay qua api, sms, cả hai (api+sms), hay - khi chưa kết nối.

Bộ lọc theo số dư lũy kế, ngày giao dịch gần nhất và các kiểu sắp xếp có ở Danh sách lệnh.

bank-account get

Xem một tài khoản theo xid. Bỏ trống xid thì CLI hiện danh sách để chọn:

$ sepay bank-account get 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98env: sandboxFIELD             VALUEID                832529c1-xxxx-xxxx-xxxx-fa163e2f7c98Bank              ACB (Ngân hàng TMCP Á Châu)Account           0000000001Holder            NGUYEN VAN ALabel             Cua hang Quan 1Type              individualConnection        apiNotifies          account number and virtual accountsAccumulated       0Last transaction  -Active            yesCreated           2026-10-17 15:00:19

bank-account update

Đổi nhãn hiển thị của tài khoản, để phân biệt các tài khoản cùng ngân hàng trong list:

$ sepay bank-account update 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98 --label "Cua hang Quan 1"env: sandboxUpdated bank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98.

Lệnh chỉ đổi nhãn (--label, bắt buộc). Trên production, lệnh cần scope bank-account:write, in dòng ! live: update bank account targets PRODUCTION rồi hỏi xác nhận. Script bạn tự viết cần đủ <bank-account-xid>, --env production và --yes (luật xác nhận).

bank-account create

Tạo thêm tài khoản ngân hàng sandbox ngoài tài khoản của sandbox init. SePay cấp số tài khoản, nên không có flag chọn số:

$ sepay bank-account create --bank ACB --account-type individual --label "Cua hang Quan 3"env: sandboxCreated bank account d6719d04-xxxx-xxxx-xxxx-a6006ab65aca.FIELD             VALUEID                d6719d04-xxxx-xxxx-xxxx-a6006ab65acaBank              ACB (Ngân hàng TMCP Á Châu)Account           0000000002Holder            NGUYEN VAN ALabel             Cua hang Quan 3Type              individualConnection        apiNotifies          account number and virtual accountsAccumulated       0Last transaction  -Active            yesCreated           2026-11-04 10:20:41First VA: SPVA00001

First VA là số VA đầu tiên SePay cấp cho tài khoản; ngân hàng không cấp VA thì không có dòng này. Notifies cho biết tài khoản báo giao dịch vào số tài khoản, vào VA, hay cả hai. Đây là lựa chọn bạn có khi tạo webhook:

Giá trị NotifiesKhi nào hiện
virtual accounts onlyNgân hàng chỉ báo giao dịch vào VA, không báo giao dịch vào số tài khoản. Gặp ở tài khoản kết nối API của một số ngân hàng, ví dụ MSB, KienLongBank, OCB, Vietcombank, và BIDV không phải tài khoản doanh nghiệp. Tài khoản có kết nối SMS không bao giờ rơi vào trường hợp này
account number and virtual accountsNgân hàng cấp VA chính thức cho loại tài khoản này, hoặc tài khoản kết nối qua SMS. Webhook nhận được cả giao dịch vào số tài khoản lẫn vào VA
account number, and any virtual account it hasCác tài khoản còn lại. Webhook nhận giao dịch vào số tài khoản, và vào VA nếu tài khoản có VA

Với --json, ba trường tương ứng là connection_type (api, sms, api+sms hoặc null khi chưa kết nối), official_va_supported và va_only.

FlagKiểuBắt buộcMô tả
--bankstringCóMã ngân hàng, ví dụ ACB
--account-typestringCóindividual | business_household | enterprise
--connectionstringKhôngapi | sms. Mặc định api; sms chỉ dùng được với gói còn hỗ trợ SMS
--holder-namestringKhôngTên chủ tài khoản; tự tạo nếu bỏ trống
--labelstringKhôngNhãn hiển thị

bank-account delete

Xóa một tài khoản ngân hàng sandbox:

$ sepay bank-account delete d6719d04-xxxx-xxxx-xxxx-a6006ab65aca --yesenv: sandboxDeleted bank account d6719d04-xxxx-xxxx-xxxx-a6006ab65aca.
Xóa tài khoản xóa luôn VA và giao dịch của nó

Lệnh luôn hỏi xác nhận, chạy trong script thì cần --yes. Tài khoản đã xóa không khôi phục được, kèm theo các VA và giao dịch của nó. Muốn xóa toàn bộ dữ liệu sandbox của công ty thì dùng sandbox reset.

Thông báo lỗi

Thông báoNguyên nhânCách xử lý
a bank account xid is requiredChạy trong script mà không truyền xidTruyền xid lấy từ bank-account list
--label is requiredupdate thiếu --labelThêm --label "<nhãn>"
requires confirmation; pass --yesLệnh cần xác nhận trên sandbox nhưng không có terminal để hỏiKiểm tra lại xid rồi thêm --yes
... ask the user to run this command in their own terminalupdate trên production không đạt luật xác nhậnTự chạy lệnh trong terminal và trả lời y
bank-account create is sandbox-only; drop --env productionChạy create (hoặc delete, thông báo ghi tên lệnh đó) với --env productionBỏ --env production; tài khoản thật liên kết trên my.sepay.vn
! the account was created but its first VA was notTài khoản đã tạo nhưng SePay chưa cấp được VA đầu tiênCấp VA bằng sepay va issue --bank-account <bank-account-xid> trước khi giả lập va_credit