CLI

Install it globally, or run it without installing through npx. It needs Node 20 or later.

npm install -g @capay/cli

Paste a secret key when prompted. It is stored in your operating system keychain when one is available, otherwise in a config file with 0600 permissions, and it is never echoed to the terminal or written to your shell history.

$ capay login
? Paste your secret key (sk_test_... or sk_live_...): ********
Logged in as Sunrise Electronics (Default app, SANDBOX).

Shows the merchant, app, environment and the scopes the stored key carries. This is the fastest way to confirm you are pointed at the sandbox and not at production.

$ capay whoami
merchant   Sunrise Electronics (mch_8fK2q0Zr41Xa)
app        Default app (SANDBOX)
key        sk_test_8fK2  scopes: collections:read, collections:write, events:read

Polls GET /v1/events and re-POSTs each new event to your local URL as a real signed delivery, using a signing secret the CLI prints once. Your verification code therefore runs unchanged. There is no inbound tunnel: nothing on the internet can reach your machine through this command.

$ capay listen --forward-to http://localhost:3000/webhooks
Local signing secret (shown once): whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Polling GET /v1/events every 2s. Ctrl-C to stop.
12:00:04  evt_2n4Kq8Zr41Xa  collection.completed  -> 200 (142 ms)
12:00:09  evt_5r7Lm9Zr41Xa  payout.failed         -> 500 (87 ms)  will retry

The secret the CLI prints is a local one, not your endpoint's whsec_. Point your development configuration at it, and read the delivery contract in the webhooks guide: Webhooks

Produces an outbound event by making the real API calls that cause it: a create with X-Scenario-Key, then POST /v1/test/advance to make the simulator steps due now. There is no server-side trigger endpoint. Events that no public sandbox call can produce are reported as not triggerable, with the reason, instead of being faked.

$ capay trigger collection.failed --scenario failed.insufficient_funds
POST /v1/collections  X-Scenario-Key: failed.insufficient_funds  -> 201 col_7Qm3k1Xa9Zr4 (pending)
POST /v1/test/advance {"resource_type":"collection","resource_id":"col_7Qm3k1Xa9Zr4"} -> advanced: 2
collection.failed emitted. Watch it: capay listen, or GET /v1/collections/col_7Qm3k1Xa9Zr4

$ capay trigger payout.enqueued
Not triggerable: the sandbox stamps a payout `processing` on creation and the state
machine has no processing -> enqueued rule, so no public call produces this event.

Scenario keys and the magic phone numbers are listed on the sandbox page: Sandbox

Calls POST /v1/test/fund to credit your sandbox available balance, so payouts and refunds have something to spend. Sandbox keys only: a production key answers 403 sandbox_only.

$ capay fund 100000 XAF
POST /v1/test/fund {"amount":"100000","currency":"XAF"} -> funded: true

The CLI uses the key you logged in with, so give it a key that carries exactly the scopes you need. A call outside the key's scopes answers 403 insufficient_scope.