Intégrer Xaalis avec un agent de code

Xaalis est conçu pour qu’un agent de code fasse une intégration avec peu ou pas d’aide humaine : la documentation est lisible par les machines, un compte de test s’ouvre en une requête et chaque résultat se simule. Deux choses restent humaines par conception — la vérification d’identité (KYC) et le passage en réel — pour qu’un agent ne puisse jamais commencer seul à déplacer de l’argent réel.

La consigne

Collez ceci dans votre agent (Claude Code, Cursor, Codex, Gemini CLI…) :

Intègre les paiements Xaalis (Wave et Orange Money) à ce projet. Lis d'abord
https://docs.xaalis.org/llms.txt, ouvre un compte de test via
POST https://sandbox-api.xaalis.org/v1/sandbox/signups, puis implémente la création de paiement avec clé
d'idempotence, le webhook signé et des tests de bout en bout. N'utilise aucune clé réelle.

Pour un résultat plus fiable, donnez-lui la skill xaalis-integration (plugin Claude Code) ou collez integrations/ai/AGENTS.xaalis.md dans votre AGENTS.md — voir Skills pour agents de code.

Ce que fait l’agent — en mode test, sans humain

Étape	Comment	Terminé quand
1. Apprendre l’API	`/llms.txt`, `/llms-full.txt`, ou l’outil MCP `xaalis_search_docs`	—
2. Ouvrir un compte de test	`POST https://sandbox-api.xaalis.org/v1/sandbox/signups` (ou l’outil MCP `xaalis_sandbox_signup`) : renvoie `sk_test_…` et `whsec_…` une seule fois — voir Mode test	les deux secrets sont dans des variables d’environnement, jamais dans le code
3. Créer les paiements côté serveur	`POST /v1/payments` avec une `Idempotency-Key` tirée de la commande, puis redirection vers `checkout_url` — voir Paiements	un paiement de test existe et la page de paiement s’ouvre
4. Vérifier les webhooks	corps brut, `Xaalis-Signature` (HMAC-SHA256), refus des horodatages de plus de 5 minutes, dédoublonnage sur l’`id` de l’événement — voir Webhooks	une mauvaise signature est refusée avec `400`
5. Livrer au bon moment	uniquement sur un webhook `payment.succeeded` vérifié ou un `GET /v1/payments/{id}` côté serveur — jamais sur la redirection	la redirection seule ne livre rien
6. Simuler chaque résultat	`POST /v1/payments/{id}/simulate` avec `succeeded` ou `failed` ; en laisser un expirer ; un retrait vers un numéro finissant par `0000` échoue — voir Mode test	chaque résultat met la commande dans le bon état
7. Dérouler la liste	Liste de vérification avant le réel	toutes les cases sont cochées

Ce qui reste humain

Étape	Pourquoi	Où
Vérification d’identité (KYC)	l’entreprise, la pièce d’identité du propriétaire et le wallet Wave qui reçoit les règlements	tableau de bord marchand, onboarding (propriétaire uniquement) — voir Tableau de bord
Validation	Xaalis examine le compte ; tant qu’il n’est pas actif, les requêtes réelles renvoient `403 merchant_not_active`	Liste de vérification
Clés réelles	un propriétaire les crée dans le tableau de bord ; elles ne s’affichent qu’une fois	Tableau de bord
Relire le travail de l’agent	une personne relit l’intégration avant que de l’argent réel circule (liste ci-dessous)	—
Wallets d’agents en réel	si votre application laisse un agent payer des personnes, seul un propriétaire peut créer et financer son wallet	Wallets d’agents

Aujourd’hui, un compte de production est ouvert par l’équipe Xaalis : demandez-le une fois la liste validée. Le compte sandbox créé par l’agent reste un compte de test.

Relire le travail de l’agent avant le réel

Les clés secrètes et le secret de webhook ne vivent que dans la configuration du serveur — pas dans le code client, une application mobile, un dépôt ou des journaux (cherchez sk_ et whsec_ dans le code).
Chaque POST /v1/payments et POST /v1/payouts envoie une Idempotency-Key liée à l’action métier, réutilisée en cas de nouvel essai. → Idempotence
Le gestionnaire de webhook lit le corps brut, compare la signature en temps constant, refuse les horodatages trop anciens, dédoublonne sur l’id, vérifie livemode, et compare amount et client_reference avec la commande.
Les montants sont des francs entiers partout.
Rien n’est livré parce que le client est arrivé sur success_url.
Les erreurs sont traitées par code, pas par message. → Erreurs
L’adresse de l’API, les clés et le secret de webhook viennent de la configuration : passer en réel est un changement de configuration.

Passer en réel

Remplacez https://sandbox-api.xaalis.org par https://api.xaalis.org, la clé sk_test_ par la clé sk_live_, et le secret de webhook par celui du compte de production. Faites un petit paiement réel (100 F CFA) et regardez le webhook arriver dans GET /v1/webhook-deliveries. Le reste est dans la liste de vérification.