Integrate Xaalis with a coding agent

Xaalis is built so a coding agent can do an integration with little or no human help: the docs are machine-readable, a test account opens with one request, and every outcome can be simulated. Two things stay human by design — identity verification (KYC) and going live — so an agent can never start moving real money on its own.

The brief

Paste this into your agent (Claude Code, Cursor, Codex, Gemini CLI…):

Integrate Xaalis payments (Wave and Orange Money) into this project. First read
https://docs.xaalis.org/llms.txt, open a test account with
POST https://sandbox-api.xaalis.org/v1/sandbox/signups, then implement payment creation with an
idempotency key, the signed webhook and end-to-end tests. Use no live keys.

For a more reliable result, give it the xaalis-integration skill (Claude Code plugin) or paste integrations/ai/AGENTS.xaalis.md into your AGENTS.md — see Skills for coding agents.

What the agent does — test mode, no human needed

Step	How	Done when
1. Learn the API	/llms.txt, /llms-full.txt, or the MCP tool xaalis_search_docs	—
2. Open a test account	POST https://sandbox-api.xaalis.org/v1/sandbox/signups (or the MCP tool xaalis_sandbox_signup): returns sk_test_… and whsec_… once — see Test mode	both secrets are in environment variables, never in code
3. Create payments on the server	POST /v1/payments with an Idempotency-Key derived from the order, then redirect to checkout_url — see Payments	a test payment exists and the checkout opens
4. Verify webhooks	raw body, Xaalis-Signature (HMAC-SHA256), reject timestamps older than 5 minutes, deduplicate on event id — see Webhooks	a wrong signature is rejected with 400
5. Fulfil the right way	only on a verified payment.succeeded webhook or a server-side GET /v1/payments/{id} — never on the redirect	the redirect alone ships nothing
6. Simulate every outcome	POST /v1/payments/{id}/simulate with succeeded or failed; let one expire; a payout to a number ending in 0000 fails — see Simulating outcomes	each outcome reaches the right order state
7. Run the checklist	Go-live checklist	every box is ticked

What stays human

Step	Why	Where
Identity verification (KYC)	the business, the owner’s identity document and the Wave wallet that receives settlements	merchant dashboard, onboarding (owner only) — see Dashboard
Approval	Xaalis reviews the account; until it is active, live requests return 403 merchant_not_active	Go-live checklist
Live keys	an owner creates them in the dashboard; they are shown once	Dashboard
Reviewing the agent’s work	a person reads the integration before real money flows (checklist below)	—
Live agent wallets	if your app lets an agent pay people out, only an owner can create and fund its wallet	Agent wallets

Today a production account is opened by the Xaalis team: ask for it once the checklist passes. The sandbox account the agent created stays test-only.

Review the agent’s work before going live

• Secret keys and the webhook secret live only in server-side configuration — not in client code, a mobile app, a repository or logs (search the codebase for sk_ and whsec_).
• Every POST /v1/payments and POST /v1/payouts sends an Idempotency-Key tied to the business action, reused on retry. → Idempotency
• The webhook handler reads the raw body, compares the signature in constant time, rejects old timestamps, deduplicates on event id, checks livemode, and compares amount and client_reference with the order.
• Amounts are whole XOF integers everywhere.
• Nothing is fulfilled because the customer reached success_url.
• Errors are handled by code, not by message. → Errors
• The base URL, keys and webhook secret come from configuration, so going live is a configuration change.

Switch to live

Swap https://sandbox-api.xaalis.org for https://api.xaalis.org, the sk_test_ key for the sk_live_ one, and the webhook secret for the production account’s. Make one small real payment (100 F CFA) and watch the webhook arrive in GET /v1/webhook-deliveries. The rest is in the Go-live checklist.