Bank Hub trong SePay CLI

Thử tích hợp Bank Hub trên sandbox bằng SePay CLI, từ lúc công ty liên kết tài khoản ngân hàng tới khi IPN giao dịch về handler trên máy bạn.

||
Chỉ chạy trên sandbox

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:

Code
1
2
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 listen không áp dụng cho Bank Hub; nhóm này dùng bankhub 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:49Z

Credential 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ểuBắt buộcMô tả
<url>stringCóĐịa chỉ http hoặc https công khai nhận IPN
--api-keystringKhôngKhó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:      ****1234

Khi đã 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ểuBắt buộcMô tả
<url>stringCóĐịa chỉ nhận sự kiện
--secretstringKhôngKhóa ký; - đọc từ stdin
--eventsstring[]Không'*' (tất cả) hoặc danh sách sự kiện cách nhau bằng dấu phẩy
--activeboolKhôngMặ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:   *
webhook set ghi đè webhook cũ, không lấy lại được

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ố

FlagLệnhKiểuBắt buộcMô tả
--namecreate, updatestringcreateTên đầy đủ. Trong terminal, bỏ trống thì CLI hỏi
--statuscreate, update, liststringKhôngcreate: 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-amountupdatestringKhôngHạn mức giao dịch: số nguyên hoặc Unlimited
--payment-codeupdatestringKhôngon | off
--searchliststringKhôngTì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 Unlimited

Ghi chú

  • company create in ✓ 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 Active và có hạn mức lớn hơn 0 hoặc Unlimited. company create khô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 list liệt kê công ty.

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ố

FlagKiểuBắt buộcMô tả
--companystringCóXid công ty. Trong terminal, bỏ trống thì CLI cho chọn từ danh sách
--purposestringCó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-accountstringVới UNLINK_BANK_ACCOUNTXid 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-uristringKhôngURL 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
--languagestringKhôngvi (mặc định) | en
--mobileboolKhôngĐánh dấu luồng của ứng dụng di động
--show-tokenboolKhôngIn 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:00

Ghi 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 --json báo accounts_total lớn hơn 0; URL webhook nhận sự kiện BANK_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ố

FlagKiểuBắt buộcMô tả
--forwardstringTrong scriptĐịa chỉ handler. Trong terminal, bỏ trống thì CLI hỏi
--printboolKhôngIn toàn bộ payload
--eventsstring[]KhôngChỉ chuyển transaction_credit, transaction_debit
--bank-accountstringKhôngChỉ 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 định 7, tối đa 10; 0 là 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.

FlagKiểuBắt buộcMô tả
--bank-accountstringCóXid tài khoản đã liên kết
--amountintCóSố tiền VND, lớn hơn 0
--contentstringCóNội dung giao dịch
--typestringKhôngcredit (mặc định) | debit
--referencestringKhôngMã 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 listKiểuMô tả
--companystringXid công ty
--bank-accountstringXid tài khoản
--from, --tostringKhoảng ngày YYYY-MM-DD
--typestringcredit | debit
--searchstringTìm giao dịch
--page, --per-pageintPhâ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-25

Xem 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_codeNguyên nhân
no IPN endpoint configured, no bank account is linked (ipn listen)Cảnh báo, lệnh vẫn chạyChư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ạyChưa có merchant sandbox; chạy sepay bankhub auth để tạo
Không có IPN sau giao dịch thửKhông có lỗiCô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 merchant1 / 404Xid 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 get1 / errorĐã truyền xid thay vì giá trị token
bankhub_provision_failed, bankhub_token_failed1SePay 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 webhookKhông có lỗiChưa đặt webhook, hoặc --events không có sự kiện đó