SDK Node / TypeScript

@xaalis/sdk est le client TypeScript côté serveur (Node 20+, aucune dépendance à l’exécution). Il n’est pas encore publié sur npm : utilisez-le depuis le monorepo.

import { XaalisClient, XaalisApiError, constructEvent, formatXof } from "@xaalis/sdk";

const xaalis = new XaalisClient({ secretKey: process.env.XAALIS_SECRET_KEY!, baseUrl: "https://api.xaalis.org" });

const payment = await xaalis.payments.create(
  { amount: 15000, description: "Commande #1042", client_reference: "order_1042", success_url: "https://shop.example/merci" },
  { idempotencyKey: "payment:order_1042" }, // obligatoire, et identique à chaque nouvelle tentative
);
console.log(formatXof(payment.amount), payment.checkout_url);

API	Méthodes
`payments`	`create`, `retrieve`, `list`, `listAll` (itérateur asynchrone sur toutes les pages)
`payouts`	`create`, `retrieve`, `list`, `listAll`
`balance`	`retrieve`
`agentWallets`	création, alimentation, récupération, désactivation, clés, versements — voir Portefeuilles d’agent
`testHelpers`	`simulatePayment(id, "succeeded" \| "failed")` — clés de test uniquement
`constructEvent(raw, header, secret)`	vérifie et lit un webhook

Les remboursements et les abonnements arrivent dans le SDK ; en attendant, appelez directement POST /v1/payments/{id}/refunds et les endpoints d’abonnement.

Ce qu’il fait pour vous

Idempotence explicite : chaque création prend une idempotencyKey que vous choisissez (l’identifiant de votre commande ou de votre retrait) ; elle reste la même d’une tentative à l’autre, y compris après un redémarrage.
Nouvelles tentatives seulement quand c’est sûr : lectures en cas d’erreur réseau, de 429 ou de 5xx, et toute requête répondue 429, en respectant Retry-After (maxRetries, 2 par défaut). Si l’issue d’une écriture est inconnue (error.outcomeUnknown), relancez-la vous-même avec la même clé.
Erreurs : XaalisApiError (status, code, message), XaalisNetworkError / XaalisProtocolError (outcomeUnknown), XaalisSignatureError.
Sécurité : refuse de s’exécuter dans un navigateur et refuse une clé de production en http://.

try {
  await xaalis.payouts.create({ amount: 5000, provider: "wave", recipient: { phone: "+221770000001" } }, { idempotencyKey: "withdraw:2026-09-27" });
} catch (err) {
  if (err instanceof XaalisApiError && err.code === "insufficient_funds") {
    /* afficher « solde insuffisant » */
  } else throw err;
}

Une intégration complète qui l’utilise : Exemple de boutique. Référence complète : packages/sdk/README.md (en anglais).