Gestion des erreurs

Passez onError et affichez le message. La plupart des échecs peuvent être résolus par le client, et le silence ne fait que le pousser à réessayer à l’aveugle.

onError={(error) => {
  console.error('[stablezact]', error);
  showBanner(String(error));
}}

Échecs courants

Mauvais réseau. Le wallet est sur une autre chaîne que celle du paiement. Le SDK propose de changer de chaîne ; certains wallets refusent le changement programmatique et le client doit le faire lui-même.

Gas insuffisant. Le client détient le stablecoin mais pas de monnaie native pour payer le transfert. Détecté avant l’envoi par la vérification du solde.

Refusé dans le wallet. Le client a refusé la signature. Ce n’est pas une erreur dont il faut s’excuser. Laissez-le réessayer.

Paiement expiré. Les paiements ne restent pas ouverts indéfiniment. Créez-en un nouveau.

Chaîne non configurée. La création d’un paiement sur une chaîne sans wallet de règlement est rejetée, avec une erreur qui nomme la chaîne. Corrigez cela dans vos paramètres marchand, pas dans le code.

Ce qu’il ne faut pas faire

Ne relancez pas la création d’un paiement sans clé d’idempotence. Envoyez un en-tête Idempotency-Key, ou au minimum le même orderId, afin que le serveur puisse distinguer une nouvelle tentative d’un second achat. Consultez Réessayer en toute sécurité.

Ne considérez pas une erreur 500 sur une lecture de paiement comme une panne avant d’avoir vérifié l’ID. Un ID de paiement inconnu renvoie actuellement 500 au lieu de 404. Consultez Erreurs.