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ệnh | Việc | Môi trường |
|---|---|---|
bank-account list | Liệt kê tài khoản, lấy xid | Cả hai |
bank-account get | Xem một tài khoản | Cả hai |
bank-account update | Đổi nhãn hiển thị | Cả hai |
bank-account create | Tạo tài khoản thử | Sandbox |
bank-account delete | Xó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| Flag | Kiểu | Mô tả |
|---|---|---|
--search | string | Tìm theo tên chủ tài khoản, nhãn hoặc số tài khoản |
--bank | string | Lọc theo ngân hàng, ví dụ ACB |
--active | string | 1 chỉ tài khoản đang bật, 0 chỉ tài khoản đã tắt |
--page, --per-page | int | Phâ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:19bank-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: SPVA00001First 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ị Notifies | Khi nào hiện |
|---|---|
virtual accounts only | Ngâ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 accounts | Ngâ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 has | Cá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.
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--bank | string | Có | Mã ngân hàng, ví dụ ACB |
--account-type | string | Có | individual | business_household | enterprise |
--connection | string | Không | api | sms. Mặc định api; sms chỉ dùng được với gói còn hỗ trợ SMS |
--holder-name | string | Không | Tên chủ tài khoản; tự tạo nếu bỏ trống |
--label | string | Không | Nhã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.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áo | Nguyên nhân | Cách xử lý |
|---|---|---|
a bank account xid is required | Chạy trong script mà không truyền xid | Truyền xid lấy từ bank-account list |
--label is required | update thiếu --label | Thêm --label "<nhãn>" |
requires confirmation; pass --yes | Lệnh cần xác nhận trên sandbox nhưng không có terminal để hỏi | Kiểm tra lại xid rồi thêm --yes |
... ask the user to run this command in their own terminal | update trên production không đạt luật xác nhận | Tự chạy lệnh trong terminal và trả lời y |
bank-account create is sandbox-only; drop --env production | Chạy create (hoặc delete, thông báo ghi tên lệnh đó) với --env production | Bỏ --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 not | Tài khoản đã tạo nhưng SePay chưa cấp được VA đầu tiên | Cấp VA bằng sepay va issue --bank-account <bank-account-xid> trước khi giả lập va_credit |