Payment codes in SePay CLI

List, update and add payment code structures with SePay CLI so transfers match orders by their content, then test code detection in the sandbox.

||

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        on

Pay 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

ParameterTypeRequiredDescription
<prefix> or --prefixstringYesThe 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-typestringNoNumberOnly (digits only) | NumberAndLetter (digits and letters)
--suffix-fromintNoMinimum suffix length, 1 to 30
--suffix-tointNoMaximum suffix length, 1 to 30; not less than --suffix-from
--enable, --disableboolNoTurn payment code recognition on or off for the whole company
--structurestringNoCurrent prefix of the structure to edit, when the company has several
--activeboolNoDefault 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        on

Notes

  • 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, use paycode create.
  • Passing only flags, without a prefix, keeps the stored prefix.
  • Run sepay paycode update with 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 list is paycode ls, paycode update is paycode 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 production and --yes together; --enable, --disable run only in a terminal (confirmation rule). A missing paycode:write scope 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.
Changing the structure on production takes effect immediately

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

ParameterTypeRequiredDescription
<prefix> or --prefixstringYesThe 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-typestringYesNumberOnly (digits only) | NumberAndLetter (digits and letters)
--suffix-fromintYesMinimum suffix length, 1 to 30
--suffix-tointYesMaximum suffix length, 1 to 30; not less than --suffix-from
--activeboolYes--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        on

Notes

  • 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, use sepay paycode update --structure <prefix>.
  • Running the command again after a dropped connection never creates the structure twice. In a script, pass --idempotency-key as 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; --yes can't confirm it. A structure created with --active matches 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 symptomCause
code is empty in the webhook even though the customer included a codeRecognition is off, the code doesn't match the structure, or the bank truncated the content (compare with paycode list)
paycode_prefix_existspaycode 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