SDK Node / TypeScript

@xaalis/sdk est le client TypeScript côté serveur (Node 20+, aucune dépendance à l’exécution, licence MIT).

npm install https://docs.xaalis.org/downloads/xaalis-sdk-0.1.0.tgz     # `npm install @xaalis/sdk` dès sa publication sur npm

Toutes les versions, leurs sommes de contrôle et les autres paquets : Téléchargements.

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

// baseUrl vaut https://api.xaalis.org par défaut (toujours en HTTPS : une clé réelle est refusée en HTTP simple).
// Les clés d’un compte sandbox appartiennent à https://sandbox-api.xaalis.org : indiquez-le pour celles-ci.
const xaalis = new XaalisClient({ secretKey: process.env.XAALIS_SECRET_KEY!, baseUrl: process.env.XAALIS_API_URL });

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`
`payments.refunds`	`create(paymentId, { idempotencyKey })`, `list(paymentId)` — voir Remboursements
`subscriptions`	`create`, `retrieve`, `list`, `listAll`, `cancel`, `testAdvance` (clés de test) — voir Abonnements
`invoices`	`retrieve`, `list`, `listAll` (filtres `subscription`, `status`)
`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

const refund = await xaalis.payments.refunds.create(payment.id, { idempotencyKey: `refund:${payment.id}` });

const sub = await xaalis.subscriptions.create(
  { customer: { phone: "+221771234567", name: "Awa Ndiaye" }, amount: 5_000, interval: "month" },
  { idempotencyKey: "subscription:customer-123:monthly" },
);
// Envoyez sub.latest_invoice?.hosted_invoice_url au client (le lien reste valable d'une tentative à l'autre).

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).