Idempotence

Le réseau peut lâcher. Quand une requête expire, vous ne savez pas si elle est arrivée chez Xaalis. Les clés d’idempotence rendent la nouvelle tentative sûre : renvoyez le même en-tête Idempotency-Key et vous récupérez l’objet d’origine au lieu d’un deuxième paiement ou d’un deuxième versement.

POST /v1/payments
Idempotency-Key: order-1042

• Obligatoire sur POST /v1/payouts, les remboursements, la création, l’annulation et l’avance d’un abonnement, ainsi que les écritures des portefeuilles d’agent (une requête sans clé reçoit 400) ; fortement recommandé sur POST /v1/payments.
• Les clés sont propres à votre compte marchand ; c’est à vous de les rendre uniques — votre numéro de commande ou de retrait convient très bien.
• Même clé, même requête → l’objet d’origine (y compris en cas de nouvelles tentatives simultanées, pour les paiements).
• Même clé, paramètres différents → 409 idempotency_conflict (le montant d’un paiement ; le montant, le prestataire ou le bénéficiaire d’un versement). Rien n’est créé.
• Ne réutilisez une clé que pour relancer la même opération. Un nouveau paiement demande une nouvelle clé.

Le SDK Node vous demande la clé à chaque création : elle reste la même d’une tentative à l’autre et après un redémarrage — utilisez l’identifiant de votre commande ou de votre retrait.

Les clés sont propres à votre marchand et au mode : la même clé utilisée avec une clé de test puis avec une clé de production crée deux objets indépendants.