The bankhub commands currently run on the sandbox only, with simulated data that never touches production. On production, use the Bank Hub API.
Use the bankhub commands (short form bh) of SePay CLI to test a Bank Hub integration on the sandbox, in the merchant role (the platform that integrates Bank Hub). For concepts and the business flow, see SePay Bank Hub and Quick start.
The commands run against simulated banks. You need to be signed in, with Test mode enabled for your company, and two public URLs to receive IPNs and webhooks. The IPN URL doesn't have to process notifications, because you get a copy through bankhub ipn listen.
Commands that set, change or revoke something (company update, ipn set, webhook set, link-token revoke) ask for confirmation, on sandbox too; without a terminal, add --yes. company create and link-token create don't ask.
Command order for a test integration:
bankhub auth → ipn set → webhook set → company create → company update → link-token create→ (company links its account) → ipn listen → sandbox simulate-transaction → transaction list
- On the sandbox, the CLI creates your merchant on the first
bankhubcommand. sepay webhook listendoesn't apply to Bank Hub; this group usesbankhub ipn listen.
bankhub auth
The CLI fetches sandbox credentials when it needs them and never prints them. Check that they're ready and when they expire:
$ sepay bankhub authenv: sandboxPRODUCT ENV AUTH EXPIRESbankhub sandbox bearer 2026-11-02T08:48:49ZWhen the credential expires, the CLI fetches a new one on its own. --refresh fetches a new set right away; --insecure-storage stores the credentials in a 0600 file instead of the keychain.
bankhub ipn set
Sets where balance-change IPNs are delivered. Set the IPN and the webhook before the first company links an account, so its first transaction already has somewhere to go.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
<url> | string | Yes | A public http or https address that receives IPNs |
--api-key | string | No | A key of your choice that SePay sends in the Authorization: Apikey <key> header; - reads it from stdin; --api-key '' turns authentication off. Without the flag, the stored key is kept; in a terminal, the CLI asks whether to keep it, type a new one (hidden) or turn authentication off |
Example
Set the IPN address:
$ sepay bankhub ipn set https://example.com/bankhub-ipn --api-key <key>Show the stored IPN settings:
$ sepay bankhub ipn getenv: sandboxURL: https://example.com/bankhub-ipnKey: ****1234Once accounts are linked, ipn set updates them as well and prints Accounts: <n> of <m> updated. If the two numbers differ, some accounts still deliver to the old address: run the same command again until they match.
bankhub webhook set
Sets where linking events are delivered (account linked, account unlinked).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
<url> | string | Yes | The address that receives events |
--secret | string | No | Signing key; - reads it from stdin |
--events | string[] | No | '*' (all) or a comma-separated list of events |
--active | bool | No | Default true |
Example
Set a webhook for every event:
$ sepay bankhub webhook set https://example.com/bankhub-webhook --secret <key> --events '*'Show the current webhook (webhook get and webhook show give the same output):
$ sepay bankhub webhook listenv: sandboxURL: https://example.com/bankhub-webhookAuth: -Secret: -Content: application/jsonActive: yesEvents: *Each merchant has one webhook. The command replaces all of it (URL, key, event list), no command undoes it, and the old URL and key can't be read back. Run webhook list to see the current settings before you overwrite them.
bankhub company
Manages companies (the merchant's business customers).
Parameters
| Flag | Command | Type | Required | Description |
|---|---|---|---|---|
--name | create, update | string | create | Full name. In a terminal, leave it out and the CLI asks |
--status | create, update, list | string | No | create: Pending (default) | Active; in a terminal, leave it out and the CLI lets you pick. update and the list filter: Pending, Active, Suspended, Terminated, Cancelled, Fraud |
--transaction-amount | update | string | No | Transaction limit: an integer or Unlimited |
--payment-code | update | string | No | on | off |
--search | list | string | No | Search companies |
company update changes only the flags you pass. In a script, it needs at least one of --name, --status, --payment-code, --transaction-amount. In a terminal with no flags, the CLI asks What do you want to edit? and lets you pick Name, Status, Pay code matching and Transaction amount, each with its stored value. It always asks update company <xid>? before saving, then prints ✓ Company updated.
Example
Create a company:
$ sepay bankhub company create --name "Minh An Store" --status ActiveGive that company an unlimited transaction limit:
$ sepay bankhub company update <company-xid> --transaction-amount UnlimitedNotes
company createprints✓ created company Minh An Store (<xid>);<company-xid>is that xid.- SePay sends IPNs only for a company that is
Activewith a limit greater than 0 orUnlimited.company createcan't set the limit;company update --transaction-amountdoes. company get <xid>shows one company;company listlists them.
bankhub link-token
Creates a link the company uses to link its bank account on a page SePay hosts (hosted link).
Parameters
| Flag | Type | Required | Description |
|---|---|---|---|
--company | string | Yes | Company xid. In a terminal, leave it out and the CLI lets you pick from a list |
--purpose | string | Yes | In a terminal, leave it out and the CLI lets you pick. LINK_BANK_ACCOUNT, UNLINK_BANK_ACCOUNT, CREATE_VA, DELETE_VA, INACTIVE_VA, ACTIVE_VA (Create link token) |
--bank-account | string | With UNLINK_BANK_ACCOUNT | Xid of the account to unlink. In a terminal, leave it out and the CLI lists only the chosen company's accounts |
--redirect-uri | string | No | The URL the company returns to when done. It needs a scheme such as https://, no spaces or control characters; javascript:, data:, vbscript:, file:, blob: and about: are blocked. Write http://localhost:3000/done, not localhost:3000/done |
--language | string | No | vi (default) | en |
--mobile | bool | No | Marks the flow as a mobile-app flow |
--show-token | bool | No | Print the token value; masked by default |
Example
Create a link for the company to link an account and return to your page afterwards:
$ sepay bankhub link-token create --company <company-xid> --purpose LINK_BANK_ACCOUNT --redirect-uri https://example.com/linked✓ created link token <link-token-xid>URL: https://...Expires: 2026-09-25 15:30:00Notes
- The company links accounts through the URL in the output, then is sent back to
--redirect-uri. On the sandbox, the hosted link uses test data. - The token is printed only when you create it with
--show-token; without that flag, the token value can't be retrieved later.link-token get <token value>takes the token value, not the xid;link-token revoke <xid>takes the xid, can't be undone and asks for confirmation. - After linking:
sepay bankhub bank-account list --company <company-xid>lists the accounts (filter by bank with--bank <bank_id>),bank-account get <xid>shows one account with its virtual accounts;ipn get --jsonreportsaccounts_totalgreater than 0; the webhook URL receives aBANK_ACCOUNT_LINKEDevent.
bankhub ipn listen
Forwards a copy of each IPN to a handler on your machine. SePay still delivers to the IPN URL you set, and the CLI pushes an extra copy to your handler.
Parameters
| Flag | Type | Required | Description |
|---|---|---|---|
--forward | string | In scripts | Handler address. In a terminal, the CLI prompts if you omit it |
--print | bool | No | Print the full payload |
--events | string[] | No | Forward only transaction_credit, transaction_debit |
--bank-account | string | No | Forward only IPNs for this account (xid) |
Other flags: sepay bankhub ipn listen --help.
Example
$ 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= is the Bank Hub transaction ID (use it with bankhub transaction get); ba= is the account xid. IPN structure, authentication and responses: Balance change notifications.
Notes
- Each copy carries the same body and headers your IPN URL just received,
Authorizationincluded. That header goes only to a handler on your machine (localhost); any other address doesn't get it unless you add--forward-credentials. - The command copies SePay's first delivery only, not SePay's own retries.
- When your handler can't be reached (connection error, timeout), the CLI resends on SePay's retry schedule (
--forward-retries, default7, at most10;0sends once). A 4xx or 5xx answer isn't resent.
bankhub sandbox simulate-transaction
Simulates a transaction on a linked account.
| Flag | Type | Required | Description |
|---|---|---|---|
--bank-account | string | Yes | xid of the linked account |
--amount | int | Yes | Amount in VND, greater than 0 |
--content | string | Yes | Transaction content |
--type | string | No | credit (default) | debit |
--reference | string | No | Reference number |
Simulate 50,000 VND coming in:
$ sepay bankhub sandbox simulate-transaction --bank-account <bank-account-xid> --amount 50000 --content "Thanh toan DH1709"The command prints ✓ mock transaction created with the transaction ID, reference number, amount and balance.
bankhub transaction
Looks up a company's transactions.
transaction list flag | Type | Description |
|---|---|---|
--company | string | Company xid |
--bank-account | string | Account xid |
--from, --to | string | Date range YYYY-MM-DD |
--type | string | credit | debit |
--search | string | Search transactions |
--page, --per-page | int | Pagination; up to 100 |
List one company's transactions in a date range:
$ sepay bankhub transaction list --company <company-xid> --from 2026-09-01 --to 2026-09-25Show one transaction:
$ sepay bankhub transaction get <transaction_id>transaction get takes the Bank Hub transaction ID (transaction_id) from the list or from txn=, not an xid.
Error codes
| Message or code | Exit / error_code | Cause |
|---|---|---|
no IPN endpoint configured, no bank account is linked (ipn listen) | Warning; the command keeps running | No IPN URL is set yet, or no company has finished linking |
this company has no Bank Hub sandbox merchant (ipn listen) | Warning; the command keeps running | There's no sandbox merchant yet; run sepay bankhub auth to create it |
| No IPN after a test transaction | No error | The company isn't Active or its limit is 0 (company update <company-xid> --status Active --transaction-amount Unlimited) |
not found, or not visible to this merchant | 1 / 404 | The xid or ID doesn't exist, or belongs to another merchant (wrong environment) |
Không tìm thấy tài nguyên from link-token get | 1 / error | You passed the xid instead of the token value |
bankhub_provision_failed, bankhub_token_failed | 1 | SePay hasn't finished creating the sandbox merchant or couldn't issue a credential; run again, and report it to SePay if it keeps failing |
| Linking events don't reach the webhook URL | No error | No webhook is set, or --events doesn't include that event |