To have a bank transfer match an order by its content, set a payment code structure with paycode (a company can have several structures, one prefix each): SePay reads the code from the transfer content and returns it in the webhook's code field. The other way is to give each order its own account number; see Virtual accounts (VA).
Configure payment codes explains the setup; Webhook integration shows how to read code in the webhook.
The commands run on both sandbox and production. On production, paycode update and paycode create need the paycode:write scope and the read commands need read. You need to be signed in.
paycode list
Shows the current payment code structure.
$ sepay paycode listPay code: onPREFIX FROM TO TYPE ACTIVEDH 4 10 NumberOnly onPay code shows whether payment code recognition is on (on) or off (off) for the whole company.
paycode update
Sets the payment code structure: a fixed prefix (for example DH) and the suffix length.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
<prefix> or --prefix | string | Yes | The prefix, 2 to 5 letters; SePay stores it in uppercase and matches it case-insensitively. Use --prefix when your prefix collides with the keywords on, off, yes, no, true, false |
--character-type | string | No | NumberOnly (digits only) | NumberAndLetter (digits and letters) |
--suffix-from | int | No | Minimum suffix length, 1 to 30 |
--suffix-to | int | No | Maximum suffix length, 1 to 30; not less than --suffix-from |
--enable, --disable | bool | No | Turn payment code recognition on or off for the whole company |
--structure | string | No | Current prefix of the structure to edit, when the company has several |
--active | bool | No | Default true. --active=false disables only the structure you're editing |
Example
$ sepay paycode update DH --character-type NumberOnly --suffix-from 4 --suffix-to 10env: sandboxPay code updated.Pay code: onPREFIX FROM TO TYPE ACTIVEDH 4 10 NumberOnly onNotes
- Flags you leave out keep their current values. If the company has no structure yet, the prefix is required and the command creates a default structure: a 3 to 10 character suffix,
NumberOnly. - The command edits one structure and keeps the others. Without
--structure, the CLI asks which one to edit when it runs in a terminal and the company has several; in a script it edits the first active structure. Passing a different prefix renames that structure's prefix; to add a new structure, usepaycode create. - Passing only flags, without a prefix, keeps the stored prefix.
- Run
sepay paycode updatewith no arguments in a terminal and the CLI asks what to change (prefix, suffix length, character type, structure on/off, recognition on/off), showing the stored value of each. - Aliases:
paycode listispaycode ls,paycode updateispaycode edit. - On production, the command prints
env: production, then! live: update pay code targets PRODUCTION, and asks for confirmation. A script you write yourself needs--structure <prefix>,--env productionand--yestogether;--enable,--disablerun only in a terminal (confirmation rule). A missingpaycode:writescope makes it exit with code 5. - When you rename or drop a prefix that a Haravan, Shopify or Sapo connection still uses, the command prints
Warning: ... connection(s) still use a pay code prefix this list no longer has. Update the prefix in those connections in my.sepay.vn.
Payments that customers are still sending with the old prefix keep arriving in the account, but they no longer match orders automatically. Find and reconcile them with sepay transaction list (see Transactions).
paycode create
Adds one payment code structure at the end of the list, for example when website orders use the DH prefix and app orders use APP. The other structures and the company's recognition switch stay as they are; to change those, use paycode update.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
<prefix> or --prefix | string | Yes | The new prefix, 2 to 5 letters, not already used by the company (case-insensitive). In a terminal, the CLI asks for it if you leave it out |
--character-type | string | Yes | NumberOnly (digits only) | NumberAndLetter (digits and letters) |
--suffix-from | int | Yes | Minimum suffix length, 1 to 30 |
--suffix-to | int | Yes | Maximum suffix length, 1 to 30; not less than --suffix-from |
--active | bool | Yes | --active to start matching transactions right away, --active=false to create it switched off |
Example
$ sepay paycode create APP --character-type NumberOnly --suffix-from 4 --suffix-to 8 --active✓ Created pay code structure APP.Pay code: onPREFIX FROM TO TYPE ACTIVEDH 4 10 NumberOnly onAPP 4 8 NumberOnly onNotes
- The command has no defaults. In a terminal, the CLI asks for any missing parameter. In a script, a missing or invalid parameter makes it exit with code 2 before anything is sent to SePay.
- A prefix the company already has fails with
paycode_prefix_exists. To change that structure, usesepay paycode update --structure <prefix>. - Running the command again after a dropped connection never creates the structure twice. In a script, pass
--idempotency-keyas shown in Idempotency. - On production, the command prints
! live: create pay code structure APP targets PRODUCTION(with your prefix) and asks for confirmation before it creates the structure. A create command has no id, so on production it runs only in a terminal;--yescan't confirm it. A structure created with--activematches transactions immediately.
Verify matching in the sandbox
Open webhook listen to see the webhook's code, then create a simulated transaction with sandbox simulate.
To test your payment code structure, put the code in the transaction content with --override content=.... SePay detects the code from the content as it would on a real transaction:
$ sepay sandbox simulate payment_in --bank-account <bank-account-xid> --amount 50000 --override content="DH1709 thanh toan don hang"--code DH1709 only pre-fills the webhook's code field and skips the payment code structure, so it can't tell you whether your configuration detects the code. --code takes at most 10 characters; test a longer code with --override content=....
Look up the transaction by code with sepay transaction list --search DH1709. To test a VA, see Test a VA in the sandbox.
Error messages
| Message or symptom | Cause |
|---|---|
code is empty in the webhook even though the customer included a code | Recognition is off, the code doesn't match the structure, or the bank truncated the content (compare with paycode list) |
paycode_prefix_exists | paycode create used a prefix the company already has; pick another prefix, or edit that structure with paycode update --structure <prefix> |
--suffix-from is required (or another flag) | In a script, paycode create needs all of --suffix-from, --suffix-to, --character-type and --active |