Démarrage rapide

Il vous faut une clé secrète de test (sk_test_…). En local, yarn bootstrap en affiche une pour le commerçant de démonstration ; un opérateur peut en émettre d’autres depuis la console opérateur (en anglais). Les clés ne sont affichées qu’une seule fois : conservez-les côté serveur.

1. Créer un paiement (votre serveur)

curl -s -X POST http://localhost:4000/v1/payments \
  -H "Authorization: Bearer $XAALIS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{"amount":15000,"description":"Commande #1042","client_reference":"order_1042","success_url":"https://shop.example/merci"}'

{
  "id": "pay_…", "object": "payment", "livemode": false,
  "amount": 15000, "currency": "XOF", "fee": 225, "net": 14775,
  "status": "requires_payment_method",
  "checkout_url": "http://localhost:3000/pay/pay_…?cs=pay_…_secret_…",
  "expires_at": "…"
}

fee correspond à vos frais Xaalis (1,5 % par défaut, arrondis au franc supérieur) ; net est ce qui arrive sur votre solde.

2. Envoyer le client vers checkout_url

La page de paiement hébergée lui permet de choisir Wave ou Orange Money. En mode test, les deux mènent à une page de portefeuille de test avec Approuver / Refuser : aucun argent réel ne circule.

Depuis un script, vous pouvez aussi jouer le rôle du client :

curl -s -X POST "http://localhost:4000/v1/payments/$PAYMENT_ID/simulate" \
  -H "Authorization: Bearer $XAALIS_KEY" -H "Content-Type: application/json" \
  -d '{"outcome":"succeeded"}'

3. Confirmer avec un webhook, pas avec la redirection

Un client qui arrive sur votre success_url ne prouve rien (il peut taper cette URL lui-même). Livrez la commande quand vous recevez le webhook signé payment.succeeded, ou quand GET /v1/payments/{id} indique succeeded.

4. Vérifier votre solde

curl -s http://localhost:4000/v1/balance -H "Authorization: Bearer $XAALIS_KEY"
# {"object":"balance","livemode":false,"currency":"XOF","available":14775,"pending_payouts":0}

Ensuite : Paiements pour le cycle de vie complet, ou le SDK Node pour vous passer de curl.