SDK Python

xaalis (dans integrations/sdk-python) encapsule l’API pour les serveurs Python 3.9+. Bibliothèque standard uniquement — ni requests, ni httpx — et entièrement annoté en types. Il n’est pas encore publié sur PyPI : pip install ./integrations/sdk-python.

import os
from xaalis import Xaalis, XaalisAPIError, construct_event, format_xof

xaalis = Xaalis(os.environ["XAALIS_SECRET_KEY"], base_url="http://localhost:4000")

payment = xaalis.payments.create(
    amount=15000,
    description="Commande #1042",
    client_reference="order_1042",
    success_url="https://shop.example/merci",
    idempotency_key="payment:order_1042",
)
print(format_xof(payment["amount"]), payment["checkout_url"])

Les objets sont de simples dict typés comme des TypedDict (Payment, Payout, Balance, Account, WebhookDelivery, WebhookEvent). Chaque montant est un int en XOF.

API	Méthodes
`payments`	`create`, `retrieve`, `list`, `list_all` (générateur sur toutes les pages)
`payouts`	`create`, `retrieve`, `list`, `list_all`
`balance`	`retrieve`
`account`	`retrieve`, `update(webhook_url=...)`
`webhook_deliveries`	`list(limit=...)`
`test_helpers`	`simulate_payment(id, "succeeded" \| "failed")` — clés de test uniquement
`construct_event(raw, header, secret)`	vérifie et décode un webhook

Ce qu’il fait pour vous

Idempotence : chaque create envoie une Idempotency-Key (aléatoire si vous ne passez pas idempotency_key=) et la réutilise à chaque nouvelle tentative. Voir Idempotence.
Nouvelles tentatives : erreurs réseau, 429 et 5xx, avec un délai exponentiel et prise en compte de Retry-After — uniquement quand rejouer la requête est sans risque (lectures, PATCH, ou créations accompagnées de leur clé). Par défaut 2 nouvelles tentatives, et un délai maximal de 30 s par tentative. Les redirections ne sont jamais suivies.
Erreurs : XaalisAPIError (status, code, message, details), XaalisConnectionError, XaalisSignatureError — toutes des sous-classes de XaalisError. Les codes sont listés dans Erreurs.
Sécurité : refuse une clé de production sur http:// ; rejette les montants qui ne sont pas des int avant tout envoi ; ne met jamais la clé dans un message d’erreur ni dans repr.

try:
    xaalis.payouts.create(amount=5000, provider="wave", recipient={"phone": "+221770000001"})
except XaalisAPIError as err:
    if err.code == "insufficient_funds":
        ...  # afficher « solde insuffisant »
    else:
        raise

Webhooks

Passez les octets bruts de la requête — request.get_data() avec Flask, request.body avec Django — jamais un JSON re-sérialisé :

from xaalis import XaalisSignatureError, construct_event

try:
    event = construct_event(request.body, request.headers.get("Xaalis-Signature"), os.environ["XAALIS_WEBHOOK_SECRET"])
except XaalisSignatureError:
    return HttpResponse(status=400)
# répondre vite par un 2xx, dédoublonner sur event["id"], vérifier event["livemode"], puis traiter la commande

En mode test, xaalis.test_helpers.simulate_payment(payment["id"], "succeeded") amène le paiement à son état final et déclenche le même webhook qu’en production.

Exemples : integrations/sdk-python/examples/ (page de paiement, serveur de webhooks avec http.server, versement). Tests : cd integrations/sdk-python && python3 -m unittest discover -s tests -v. Voir aussi le SDK Node.