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 génère une clé pour chaque création et la réutilise lors de ses nouvelles tentatives automatiques ; passez votre propre clé pour rester protégé même si votre processus redémarre.