CLI

Create payment requests, provision accounts, and manage webhooks from the terminal — the same v1 API, without writing a line of integration code first.

Install

The CLI ships as an npm package with a jopay binary. Run it ad hoc with npx or install it globally:

# one-off
npx @jopay/cli --help

# or install globally
npm install -g @jopay/cli
jopay --help
Availability follows partner onboarding. If the package is not yet visible on the npm registry for your rollout, ask your JoPay contact.

Log in

Create an API key

Generate a key in the partner portal under API keys. Start with a jo_test_ key — test mode is fully isolated from live data, so you can create requests freely while you build.

Run jopay login

jopay login
# Partner API key (jo_live_... or jo_test_...): ********
# Logged in as Acme (test mode, full access) — profile "default".

The key is validated against GET /api/v1/me and stored in ~/.jopay/credentials.json (directory mode 0700, file mode 0600; best-effort on Windows). It is a revocable bearer key — revoke it in the portal at any time.

Verify

jopay whoami

Commands

jopay login | logout | whoami

jopay requests create --account-id <uuid> --amount 2050 [--currency EUR]
                      [--memo <text>] [--mode pos|invoice]
                      [--expiry-minutes 30] [--idempotency-key <key>]
                      [--metadata '{"order_id":"1234"}']
jopay requests list   [--status opened] [--proof-status verified]
                      [--account-id <uuid>] [--since <iso>] [--until <iso>]
                      [--limit 50] [--offset 0]
jopay requests get <id>
jopay requests cancel <id>

jopay accounts list   [--onboarding-status incomplete] [--disabled false]
jopay accounts get <id>
jopay accounts create [--email ..] [--display-name ..] [--app-mode personal|business] ...

jopay webhooks list | get <id> | deliveries <id> | test
jopay webhooks create --url https://example.com/hook --events "payment.verified,payment.expired"
jopay webhooks update <id> [--url ..] [--events ..] [--enable | --disable]
jopay webhooks delete <id>
jopay webhooks rotate-secret <id>

jopay mcp   # stdio MCP server — see the MCP server page

Amounts are always minor units (2050 = EUR 20.50), exactly as in the REST API. Responses are printed as JSON — the same bodies the Requests API documents.

Scripting

Add --json for compact single-line output that pipes cleanly into jq. Exit code 0means the API call returned 2xx; any error prints the API's JSON error body to stderr and exits 1.

jopay requests list --status opened --json | jq -r '.requests[].request_id'

Credentials, profiles, and environment

  • Precedence: --api-key / --base-url flags > JOPAY_API_KEY / JOPAY_BASE_URLenv vars > the stored profile.
  • Profiles: --profile staging keeps multiple keys side by side (e.g. test and live).
  • Base URL: defaults to https://admin.jopay.app; partner-scoped hosts (https://<partner-slug>.jopay.app) work the same — see Authentication.
  • CI usage: set JOPAY_API_KEYin the runner's secrets instead of writing a credentials file.

Key scoping

The CLI can do exactly what its key allows — nothing more. A key restricted to requests:read can list and fetch requests but every write returns insufficient_scope. The CLI holds no wallet keys, signs nothing, and executes nothing on-chain: it creates and reads instructions, and JoPay observes on-chain results.