Các lệnh bankhub hiện chỉ chạy trên sandbox, với dữ liệu giả lập, không ảnh hưởng đến production. Trên production, dùng API Bank Hub.
Dùng nhóm lệnh bankhub (viết tắt bh) của SePay CLI để thử tích hợp Bank Hub trên sandbox, ở vai trò merchant (nền tảng tích hợp Bank Hub). Khái niệm và luồng nghiệp vụ xem ở SePay Bank Hub và Bắt đầu nhanh.
Các lệnh chạy với ngân hàng giả lập. Bạn cần đăng nhập, công ty đã bật Test mode và hai URL công khai để nhận IPN và webhook. URL IPN không cần xử lý được thông báo, vì bạn nhận bản sao qua bankhub ipn listen.
Các lệnh đặt cấu hình, sửa hoặc thu hồi (company update, ipn set, webhook set, link-token revoke) hỏi xác nhận, kể cả trên sandbox; không có terminal thì thêm --yes. company create và link-token create không hỏi.
Thứ tự lệnh khi thử tích hợp:
bankhub auth → ipn set → webhook set → company create → company update → link-token create→ (công ty liên kết) → ipn listen → sandbox simulate-transaction → transaction list
- Trên sandbox, CLI tự tạo merchant ở lệnh
bankhubđầu tiên. sepay webhook listenkhông áp dụng cho Bank Hub; nhóm này dùngbankhub ipn listen.
bankhub auth
CLI tự lấy credential sandbox khi cần và không in credential. Kiểm tra credential đã sẵn sàng chưa và khi nào hết hạn:
$ sepay bankhub authenv: sandboxPRODUCT ENV AUTH EXPIRESbankhub sandbox bearer 2026-11-02T08:48:49ZCredential hết hạn thì CLI tự lấy bộ mới. --refresh lấy bộ mới ngay; --insecure-storage lưu credential trong tệp 0600 thay vì keychain.
bankhub ipn set
Đặt nơi nhận IPN biến động số dư. Đặt IPN và webhook trước khi công ty đầu tiên liên kết, để giao dịch đầu tiên đã có nơi nhận.
Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
<url> | string | Có | Địa chỉ http hoặc https công khai nhận IPN |
--api-key | string | Không | Khóa tự đặt, SePay gửi trong header Authorization: Apikey <khóa>; - đọc từ stdin; --api-key '' tắt xác thực. Không truyền flag thì giữ khóa đang lưu; trong terminal, CLI hỏi giữ khóa, nhập khóa mới (gõ ẩn) hoặc tắt xác thực |
Ví dụ
Đặt địa chỉ nhận IPN:
$ sepay bankhub ipn set https://example.com/bankhub-ipn --api-key <khóa>Xem cấu hình IPN đang lưu:
$ sepay bankhub ipn getenv: sandboxURL: https://example.com/bankhub-ipnKey: ****1234Khi đã có tài khoản liên kết, ipn set cập nhật luôn các tài khoản đó và in Accounts: <n> of <m> updated. Hai số lệch nhau thì một số tài khoản vẫn gửi về địa chỉ cũ: chạy lại đúng lệnh cho tới khi khớp.
bankhub webhook set
Đặt nơi nhận sự kiện liên kết (tài khoản được liên kết, hủy liên kết).
Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
<url> | string | Có | Địa chỉ nhận sự kiện |
--secret | string | Không | Khóa ký; - đọc từ stdin |
--events | string[] | Không | '*' (tất cả) hoặc danh sách sự kiện cách nhau bằng dấu phẩy |
--active | bool | Không | Mặc định true |
Ví dụ
Đặt webhook nhận mọi sự kiện:
$ sepay bankhub webhook set https://example.com/bankhub-webhook --secret <khóa> --events '*'Xem webhook đang đặt (webhook get và webhook show cho cùng kết quả):
$ sepay bankhub webhook listenv: sandboxURL: https://example.com/bankhub-webhookAuth: -Secret: -Content: application/jsonActive: yesEvents: *Mỗi merchant có một webhook. Lệnh thay toàn bộ (URL, khóa, danh sách sự kiện) và không có lệnh hoàn tác; URL và khóa cũ không xem lại được. Chạy webhook list để xem cấu hình hiện tại trước khi ghi đè.
bankhub company
Quản lý công ty (doanh nghiệp khách hàng của merchant).
Tham số
| Flag | Lệnh | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
--name | create, update | string | create | Tên đầy đủ. Trong terminal, bỏ trống thì CLI hỏi |
--status | create, update, list | string | Không | create: Pending (mặc định) | Active; trong terminal, bỏ trống thì CLI cho chọn. update và bộ lọc của list: Pending, Active, Suspended, Terminated, Cancelled, Fraud |
--transaction-amount | update | string | Không | Hạn mức giao dịch: số nguyên hoặc Unlimited |
--payment-code | update | string | Không | on | off |
--search | list | string | Không | Tìm công ty |
company update chỉ đổi các flag bạn truyền. Trong script, lệnh cần ít nhất một trong --name, --status, --payment-code, --transaction-amount. Trong terminal, chạy không kèm flag thì CLI hỏi What do you want to edit? và cho chọn các mục Name, Status, Pay code matching, Transaction amount, kèm giá trị đang lưu của từng mục. Lệnh luôn hỏi update company <xid>? trước khi lưu, xong thì in ✓ Company updated.
Ví dụ
Tạo công ty con:
$ sepay bankhub company create --name "Cửa hàng Minh An" --status ActiveĐặt hạn mức giao dịch không giới hạn cho công ty đó:
$ sepay bankhub company update <company-xid> --transaction-amount UnlimitedGhi chú
company createin✓ created company Cửa hàng Minh An (<xid>);<company-xid>là xid này.- SePay chỉ gửi IPN cho công ty đang
Activevà có hạn mức lớn hơn 0 hoặcUnlimited.company createkhông đặt được hạn mức;company update --transaction-amountđặt hạn mức. company get <xid>xem một công ty,company listliệt kê công ty.
bankhub link-token
Tạo link để công ty liên kết tài khoản ngân hàng trên trang SePay dựng sẵn (hosted link).
Tham số
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--company | string | Có | Xid công ty. Trong terminal, bỏ trống thì CLI cho chọn từ danh sách |
--purpose | string | Có | Trong terminal, bỏ trống thì CLI cho chọn. LINK_BANK_ACCOUNT, UNLINK_BANK_ACCOUNT, CREATE_VA, DELETE_VA, INACTIVE_VA, ACTIVE_VA (Tạo link token) |
--bank-account | string | Với UNLINK_BANK_ACCOUNT | Xid tài khoản cần hủy liên kết. Trong terminal, bỏ trống thì CLI chỉ liệt kê tài khoản của công ty đã chọn |
--redirect-uri | string | Không | URL công ty được đưa về sau khi xong. Có scheme như https://, không khoảng trắng hay ký tự điều khiển; javascript:, data:, vbscript:, file:, blob:, about: bị chặn. Ghi http://localhost:3000/done, không ghi localhost:3000/done |
--language | string | Không | vi (mặc định) | en |
--mobile | bool | Không | Đánh dấu luồng của ứng dụng di động |
--show-token | bool | Không | In giá trị token; mặc định bị che |
Ví dụ
Tạo link để công ty liên kết tài khoản, xong thì quay về trang của bạn:
$ sepay bankhub link-token create --company <company-xid> --purpose LINK_BANK_ACCOUNT --redirect-uri https://example.com/lien-ket-xong✓ created link token <link-token-xid>URL: https://...Expires: 2026-09-25 15:30:00Ghi chú
- Công ty liên kết tài khoản qua URL của kết quả, rồi được đưa về
--redirect-uri. Trên sandbox, hosted link dùng dữ liệu thử. - Token chỉ in ra khi tạo với
--show-token; không có flag này thì không lấy lại được giá trị token.link-token get <giá trị token>nhận giá trị token, không nhận xid;link-token revoke <xid>nhận xid, không hoàn tác và hỏi xác nhận. - Sau khi liên kết:
sepay bankhub bank-account list --company <company-xid>liệt kê tài khoản (lọc thêm theo ngân hàng bằng--bank <bank_id>),bank-account get <xid>xem một tài khoản kèm tài khoản ảo của nó;ipn get --jsonbáoaccounts_totallớn hơn 0; URL webhook nhận sự kiệnBANK_ACCOUNT_LINKED.
bankhub ipn listen
Chuyển tiếp bản sao IPN tới handler trên máy bạn. SePay vẫn gửi IPN tới URL IPN đã đặt, CLI đẩy thêm một bản sao vào handler.
Tham số
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--forward | string | Trong script | Địa chỉ handler. Trong terminal, bỏ trống thì CLI hỏi |
--print | bool | Không | In toàn bộ payload |
--events | string[] | Không | Chỉ chuyển transaction_credit, transaction_debit |
--bank-account | string | Không | Chỉ chuyển IPN của tài khoản này (xid) |
Flag khác: sepay bankhub ipn listen --help.
Ví dụ
$ sepay bankhub ipn listen --forward localhost:3000/bankhub-ipn✓ Listening for sandbox Bank Hub IPN → http://localhost:3000/bankhub-ipn (Ctrl+C to stop · retries+enter to manage)15:04:11 transaction_credit → http://localhost:3000/bankhub-ipn 200 41ms txn=<transaction_id> ba=<bank-account-xid>txn= là mã giao dịch Bank Hub (dùng với bankhub transaction get); ba= là xid tài khoản. Cấu trúc IPN, xác thực và phản hồi: Thông báo biến động số dư.
Ghi chú
- Bản sao mang đúng body và header mà URL IPN vừa nhận, kể cả
Authorization. Header này chỉ được chuyển khi handler nằm trên máy bạn (localhost); địa chỉ khác không nhận header này, trừ khi thêm--forward-credentials. - Lệnh chỉ sao lần gửi đầu tiên của SePay, không sao các lần SePay gửi lại.
- Handler không nhận được (lỗi kết nối, hết thời gian chờ) thì CLI gửi lại theo lịch gửi lại của SePay (
--forward-retries, mặc định7, tối đa10;0là một lần). Handler trả 4xx hoặc 5xx không được gửi lại.
bankhub sandbox simulate-transaction
Giả lập giao dịch trên tài khoản đã liên kết.
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--bank-account | string | Có | Xid tài khoản đã liên kết |
--amount | int | Có | Số tiền VND, lớn hơn 0 |
--content | string | Có | Nội dung giao dịch |
--type | string | Không | credit (mặc định) | debit |
--reference | string | Không | Mã tham chiếu |
Giả lập một khoản tiền vào 50.000 VND:
$ sepay bankhub sandbox simulate-transaction --bank-account <bank-account-xid> --amount 50000 --content "Thanh toan DH1709"Lệnh in dòng ✓ mock transaction created kèm mã giao dịch, mã tham chiếu, số tiền và số dư.
bankhub transaction
Truy vấn giao dịch của công ty.
Flag của transaction list | Kiểu | Mô tả |
|---|---|---|
--company | string | Xid công ty |
--bank-account | string | Xid tài khoản |
--from, --to | string | Khoảng ngày YYYY-MM-DD |
--type | string | credit | debit |
--search | string | Tìm giao dịch |
--page, --per-page | int | Phân trang; tối đa 100 |
Liệt kê giao dịch của một công ty trong khoảng ngày:
$ sepay bankhub transaction list --company <company-xid> --from 2026-09-01 --to 2026-09-25Xem một giao dịch:
$ sepay bankhub transaction get <transaction_id>transaction get nhận mã giao dịch Bank Hub (transaction_id) từ danh sách hoặc từ txn=, không nhận xid.
Mã lỗi
| Thông báo hoặc mã | Exit / error_code | Nguyên nhân |
|---|---|---|
no IPN endpoint configured, no bank account is linked (ipn listen) | Cảnh báo, lệnh vẫn chạy | Chưa đặt IPN URL, hoặc chưa có công ty nào liên kết xong |
this company has no Bank Hub sandbox merchant (ipn listen) | Cảnh báo, lệnh vẫn chạy | Chưa có merchant sandbox; chạy sepay bankhub auth để tạo |
| Không có IPN sau giao dịch thử | Không có lỗi | Công ty chưa Active hoặc hạn mức bằng 0 (company update <company-xid> --status Active --transaction-amount Unlimited) |
not found, or not visible to this merchant | 1 / 404 | Xid hoặc mã không tồn tại, hoặc không thuộc merchant (nhầm môi trường) |
Không tìm thấy tài nguyên ở link-token get | 1 / error | Đã truyền xid thay vì giá trị token |
bankhub_provision_failed, bankhub_token_failed | 1 | SePay chưa tạo xong merchant sandbox hoặc chưa cấp được credential; chạy lại, lặp lại thì báo SePay |
| Sự kiện liên kết không về URL webhook | Không có lỗi | Chưa đặt webhook, hoặc --events không có sự kiện đó |