Skip to content
Xaalis

Command-line tool

xaalis does from a terminal what the API does: create a payment and its checkout link, wait until it’s really paid, refund, pay out, read your balance, and check a webhook’s signature offline. It’s built for people, for scripts and for AI agents: every command can print the API’s JSON (--json) and returns a meaningful exit code.

Install

Section titled “Install”

Node.js 20 or later.

Terminal window
npm install -g https://docs.xaalis.org/downloads/xaalis-cli-0.1.0.tgz    # or, once published: npm install -g @xaalis/cli
xaalis --help

No install: npx https://docs.xaalis.org/downloads/xaalis-cli-0.1.0.tgz --help. Check the file against SHA256SUMS — see Downloads.

From nothing to a paid test payment

Section titled “From nothing to a paid test payment”
Terminal window
xaalis signup --email you@example.com --business "Boutique Awa"     # a sandbox account: test keys, shown once
export XAALIS_API_URL=https://sandbox-api.xaalis.org
export XAALIS_API_KEY=sk_test_…
xaalis payments create --amount 5000 --description "Robe bleue"    # prints the checkout link
xaalis payments simulate pay_… --outcome succeeded                 # test keys: act as the customer
xaalis payments wait pay_…                                         # exit code 0 once it really succeeded
xaalis balance

Commands

Section titled “Commands”
Command What it does
signup --email --business [--webhook-url] Creates a sandbox account (POST /v1/sandbox/signups) and prints its test secret key and webhook secret once
balance Available balance and payouts in progress
payments create --amount [--description] [--reference] [--phone] [--provider wave|orange_money] [--success-url] [--cancel-url] Creates a payment and prints its hosted checkout link
payments get <pay_…> · payments list [--limit] [--status] Reads payments
payments wait <pay_…> [--timeout 300] Polls until the payment is final; exit code 0 only if it succeeded
payments simulate <pay_…> --outcome succeeded|failed Test keys only: approves or declines as the customer would
refunds create <pay_…> [--confirm] · refunds list <pay_…> Refunds a payment (Refunds)
payouts create --amount --phone [--provider] [--name] [--reference] [--confirm] · payouts get <po_…> · payouts list Pays out to a wallet (Payouts); the fee is added on top
webhooks verify --signature <header> [--secret] [--payload-file] Checks a webhook’s Xaalis-Signature offline; the payload comes from the file or standard input

Options and safety

Section titled “Options and safety”
  • Key: XAALIS_API_KEY, or --key (it then ends up in your shell history). The key is never printed.
  • API: XAALIS_API_URL or --api-url; default https://api.xaalis.org. Sandbox accounts use https://sandbox-api.xaalis.org.
  • Amounts are whole F CFA: 5000 or "5 000", never 5000.50 — refused before any request.
  • Retries: every write sends an Idempotency-Key. Pass your own with --idempotency-key, or reuse the one the CLI prints, to retry a timed-out request without creating a second payment or payout (Idempotency).
  • Live money: refunds create and payouts create with a live key refuse to run without --confirm.
  • Fulfilment: a checkout page saying “paid” proves nothing. Ship on the signed payment.succeeded webhook (Webhooks) or on xaalis payments wait returning 0.
  • Exit codes: 0 done · 1 refused by Xaalis (the error code is printed), failed, or timed out · 2 usage error.

Help: contact@xaalis.org.