Use SePay CLI in scripts

Run SePay CLI safely from scripts and CI: read JSON output, then use exit codes to retry only temporary errors without creating duplicate records.

||

When a script or CI job calls SePay CLI, nobody is there to read a table or answer a confirmation prompt. The script reads data from stdout, catches errors by exit code, and reruns only on retryable errors.

Read output and exit codes

ChannelContents
stdoutData. Use --json or -o yaml for JSON or YAML; the default is a table
stderrErrors, warnings and the env: line. With --json, errors are JSON, including flag errors (error format)
Exit code0 for success; a non-zero value follows the exit code table

stdout contains only data, so you can pipe it into jq. The JSON error block is printed across several lines; a script should read the whole block and then pick out a field:

Bash
1
2
3
4
5
out=$(sepay transaction list --json 2>err.json)
code=$?
if [ "$code" -ne 0 ]; then
error_code=$(sed -n '/^{/,/^}/p' err.json | jq -r .error_code)
fi

When a CI job is cancelled (SIGINT, SIGTERM), or you press Ctrl+C or Esc at a prompt, the CLI exits with code 130 and error_code interrupted. To record the CLI version in your logs, run sepay --version --json (fields version, commit, date, go_version, os, arch).

sepay auth status --active --json returns the session state; the session field corresponds to the SESSION column of auth status.

Non-interactive mode

Without a terminal, a command that needs confirmation exits with exit code 2 before sending any request. On sandbox, --yes answers "yes" (Confirmation); on production, see the section below. Required arguments and flags must be passed in full, because without a terminal the command doesn't prompt you to choose or enter anything (if one is missing, it exits with exit code 2; see Interactive prompts for omitted arguments).

Production writes

A script you write yourself can run a command that changes data on production when the command has all three: --env production right on the command (default_env does not count), the id of the resource it changes, and --yes:

$ sepay webhook update 5f0e2a7b-xxxx-xxxx-xxxx-fa163e2f7c98 --url https://example.com/new-hook --env production --yes --json

A command without an id, such as webhook create, paycode create, paycode update --enable or a sepay api -X POST that creates a resource, runs only in a terminal: in a script it exits with exit code 2 even with --yes. The table of ids for each command is in Production writes.

Don't let an AI agent add --yes to a script that runs on production. When an agent writes the script, it leaves --yes out; you read the command and add it yourself.

Retry policy

A retryable error is exit code 1 with an error_code marked "Yes" in the Retryable column of the error code table: rate_limited, network_error, idempotency_conflict (rerun with the same key), *_provision_failed, *_token_failed. error depends: read message first. server_error is a failure on SePay's side (HTTP 5xx) and prints SePay is temporarily unavailable (HTTP 503); retry in a moment or SePay had an internal error (HTTP 500); ...: wait a moment and retry, keeping the same --idempotency-key for a command that creates data; if it keeps failing, send SePay the request_id from the JSON error block. Any other error gives the same result when you run it again, including idempotency_key_reuse (the key was already used for a different request): switch to a new key instead of rerunning.

For the transaction, bank-account, va, webhook, paycode, apikey, sandbox and sepay api commands, the CLI has already retried up to 3 times on connection loss or HTTP 429 before it returns an error to your script. The pg, bankhub and einvoice commands only retry reads on HTTP 429. The CLI never retries an HTTP 5xx on its own. A create command that sends no idempotency key is never retried.

Idempotency

If a create command is interrupted midway, you can't tell whether the server created the record. --idempotency-key <key> sends the X-Idempotency-Key header: with the same key, the server returns the result of the first call instead of creating a new record. Without the flag, the CLI generates a new key on every run.

Only these commands send a key: webhook create, webhook replay, bank-account create, va issue, va revoke, apikey create, paycode create, sandbox init and sepay api writes. The pg, bankhub, einvoice and paycode update commands send no key and ignore the flag.

Bash
1
2
3
KEY=$(uuidgen)
sepay webhook create --url https://api.congty.vn/webhooks/sepay --bank-mode all --event-type in \
--idempotency-key "$KEY"
A new key on every retry creates duplicate records

Generate KEY once, before the loop, and reuse it on every attempt. Don't use this loop for a command that sends no key, such as einvoice invoice create: each rerun can create another invoice.

A retry loop with up to 4 attempts and a growing wait, rerunning only on a retryable error_code:

Bash
1
2
3
4
5
6
7
8
9
10
KEY=$(uuidgen)
for delay in 2 4 8 16; do
sepay webhook create --url https://api.congty.vn/webhooks/sepay --bank-mode all --event-type in \
--idempotency-key "$KEY" --json 2>err.json && exit 0
case "$(sed -n '/^{/,/^}/p' err.json | jq -r .error_code)" in
rate_limited|network_error|idempotency_conflict|server_error|*_provision_failed|*_token_failed) sleep "$delay" ;;
*) cat err.json >&2; exit 1 ;;
esac
done
cat err.json >&2; exit 1