Bank Hub in SePay CLI

Test a Bank Hub integration on sandbox with SePay CLI, from a company linking its bank account to the transaction IPN reaching the handler on your machine.

||
Sandbox only

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:

Code
1
2
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 bankhub command.
  • sepay webhook listen doesn't apply to Bank Hub; this group uses bankhub 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:49Z

When 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

ParameterTypeRequiredDescription
<url>stringYesA public http or https address that receives IPNs
--api-keystringNoA 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:      ****1234

Once 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

ParameterTypeRequiredDescription
<url>stringYesThe address that receives events
--secretstringNoSigning key; - reads it from stdin
--eventsstring[]No'*' (all) or a comma-separated list of events
--activeboolNoDefault 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:   *
webhook set overwrites the old webhook for good

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

FlagCommandTypeRequiredDescription
--namecreate, updatestringcreateFull name. In a terminal, leave it out and the CLI asks
--statuscreate, update, liststringNocreate: 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-amountupdatestringNoTransaction limit: an integer or Unlimited
--payment-codeupdatestringNoon | off
--searchliststringNoSearch 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 Active

Give that company an unlimited transaction limit:

$ sepay bankhub company update <company-xid> --transaction-amount Unlimited

Notes

  • company create prints ✓ created company Minh An Store (<xid>); <company-xid> is that xid.
  • SePay sends IPNs only for a company that is Active with a limit greater than 0 or Unlimited. company create can't set the limit; company update --transaction-amount does.
  • company get <xid> shows one company; company list lists them.

Creates a link the company uses to link its bank account on a page SePay hosts (hosted link).

Parameters

FlagTypeRequiredDescription
--companystringYesCompany xid. In a terminal, leave it out and the CLI lets you pick from a list
--purposestringYesIn 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-accountstringWith UNLINK_BANK_ACCOUNTXid of the account to unlink. In a terminal, leave it out and the CLI lists only the chosen company's accounts
--redirect-uristringNoThe 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
--languagestringNovi (default) | en
--mobileboolNoMarks the flow as a mobile-app flow
--show-tokenboolNoPrint 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:00

Notes

  • 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 --json reports accounts_total greater than 0; the webhook URL receives a BANK_ACCOUNT_LINKED event.

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

FlagTypeRequiredDescription
--forwardstringIn scriptsHandler address. In a terminal, the CLI prompts if you omit it
--printboolNoPrint the full payload
--eventsstring[]NoForward only transaction_credit, transaction_debit
--bank-accountstringNoForward 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, Authorization included. 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, default 7, at most 10; 0 sends once). A 4xx or 5xx answer isn't resent.

bankhub sandbox simulate-transaction

Simulates a transaction on a linked account.

FlagTypeRequiredDescription
--bank-accountstringYesxid of the linked account
--amountintYesAmount in VND, greater than 0
--contentstringYesTransaction content
--typestringNocredit (default) | debit
--referencestringNoReference 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 flagTypeDescription
--companystringCompany xid
--bank-accountstringAccount xid
--from, --tostringDate range YYYY-MM-DD
--typestringcredit | debit
--searchstringSearch transactions
--page, --per-pageintPagination; 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-25

Show 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 codeExit / error_codeCause
no IPN endpoint configured, no bank account is linked (ipn listen)Warning; the command keeps runningNo 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 runningThere's no sandbox merchant yet; run sepay bankhub auth to create it
No IPN after a test transactionNo errorThe 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 merchant1 / 404The 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 get1 / errorYou passed the xid instead of the token value
bankhub_provision_failed, bankhub_token_failed1SePay 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 URLNo errorNo webhook is set, or --events doesn't include that event