Mode test

Sandbox et production

Testez dans le sandbox : https://sandbox-api.xaalis.org (page de paiement sur sandbox.xaalis.org), avec un compte sandbox et ses clés sk_test_. C’est un environnement séparé, avec ses propres comptes et données. La production est https://api.xaalis.org avec des clés sk_live_. Une fois en service, la production refuse les clés de test : les clés sk_test_ (et ak_test_ des agents) reçoivent 401 invalid_api_key avec un message qui renvoie vers le sandbox, et les routes réservées au test (simulation, échange entre portefeuilles) répondent 403 forbidden.

Chaque commerçant reçoit deux types de clé secrète. La clé seule détermine le mode : il n’y a aucun paramètre à passer.

	sk_test_…	sk_live_…
Prestataires	un connecteur fictif (mock) qui n’appelle jamais Wave ni Orange Money	Wave, Orange Money
Argent	aucun ; les soldes sont tenus dans des comptes test: séparés du grand livre	des XOF réels
Statut du commerçant	fonctionne tant que votre compte est pending_review	exige active (sinon 403 merchant_not_active)
livemode sur les objets	false	true

Les données de test et de production ne se mélangent jamais : un paiement de test renvoie 404 avec votre clé de production, et inversement, et l’argent de test ne peut pas être versé sur un vrai portefeuille.

Créer un compte sandbox depuis le code

Sans intervention humaine : l’API sandbox ouvre un compte de test uniquement et renvoie ses clés une seule fois.

curl -s -X POST https://sandbox-api.xaalis.org/v1/sandbox/signups \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@example.com", "business_name": "Boutique Awa", "webhook_url": "https://example.com/webhooks/xaalis" }'

{ "object": "sandbox_signup",
  "merchant": { "id": "mer_…", "object": "merchant", "name": "Boutique Awa", "email": "dev@example.com", "status": "pending_review" },
  "secret_key": "sk_test_…", "webhook_secret": "whsec_…" }

• Le compte n’a qu’une clé de test : il ne peut jamais déplacer d’argent réel. Passer en production demande une personne (vérification d’identité, validation) depuis le tableau de bord.
• Les deux secrets ne sont affichés qu’une fois : rangez-les tout de suite dans des variables d’environnement. Avec une Idempotency-Key, une relance renvoie 409 secret_unavailable (avec details.merchant_id) : les secrets ne sont jamais affichés deux fois.
• Limites : 5 inscriptions par heure et 20 par jour par adresse (429 rate_limited, respectez Retry-After). Au plus 3 comptes sandbox par e-mail, définitivement : le quatrième répond 422 limit_exceeded — inutile de réessayer, utilisez un compte existant.
• webhook_url est facultatif et doit commencer par https://. La production (api.xaalis.org) n’a pas cette route (404).
• Les agents IA font la même chose avec l’outil MCP xaalis_sandbox_signup (Agents IA).

Simuler des résultats

Pour obtenir	Faites
un paiement réussi	POST /v1/payments/{id}/simulate {"outcome":"succeeded"} — ou cliquez sur Approuver sur la page du portefeuille de test
un paiement échoué	la même chose avec "failed" — ou Refuser
un paiement expiré	ne le payez pas ; les pages de paiement expirent au bout de 30 minutes et sont clôturées par une tâche de fond dans les ~5 minutes qui suivent
un versement réussi	n’importe quel numéro de bénéficiaire, par exemple +221770000001
un versement échoué	un numéro de bénéficiaire qui se termine par 0000, par exemple +221770000000 — le montant réservé et les frais reviennent dans available
insufficient_funds	un versement supérieur à available

simulate suit le même chemin qu’une vraie notification du prestataire (boîte de réception → machine à états → grand livre → webhook) : ce que vous voyez en mode test est donc ce que fait le mode production. Avec une clé de production, il renvoie 403.

Une seule URL de webhook pour les deux modes

Votre compte n’a qu’une seule webhook_url, utilisée pour les événements de test comme de production : vérifiez toujours livemode dans le contenu reçu avant de livrer une commande. Seule une clé de production peut modifier cette URL, et chaque clé ne voit que les envois de son propre mode.