Comment confirmer un paiement en stablecoins sur votre serveur

Pourquoi votre serveur, et pas le navigateur

Un checkout qui affiche Payé n’est que ce que montre le navigateur de votre client. L’onglet peut se fermer avant de revenir sur votre site, et n’importe qui peut ouvrir votre page de succès à la main. C’est la confirmation du réseau qui rend un paiement définitif.

Cosmos Pay surveille le réseau pour vous et prévient votre serveur quand un paiement est confirmé. C’est sur votre serveur qu’il faut marquer la commande comme payée et la livrer.

Ce qu’envoie Cosmos Pay

• Un POST HTTPS vers l’endpoint que vous enregistrez, avec un événement JSON : id (il commence par evt_), type, createdAt et data. Pour un paiement, data est le paiement avec son statut, son montant, son actif, son réseau et sa transaction.
• L’en-tête X-Cosmos-Signature : t=<horodatage unix>,v1=<signature>. La signature est le HMAC-SHA256 de t, d’un point et du corps brut, avec le secret de l’endpoint comme clé, en hexadécimal.
• Les types d’événement que vous choisissez, comme PAYMENT_INTENT_SUCCEEDED, PAYMENT_INTENT_FAILED ou ZK_PAYMENT_SUCCEEDED. Comparez-les tels qu’ils sont écrits, en majuscules avec des tirets bas.
• Les en-têtes X-Cosmos-Event, X-Cosmos-Event-Id et X-Cosmos-Delivery, qui identifient l’événement et la livraison.

Les webhooks dans le SDKAPI des webhooks

Configurer un webhook, étape par étape

1. Ajoutez un endpoint

   Dans le tableau de bord, ouvrez Webhooks et ajoutez l’adresse HTTPS d’une route de votre serveur. Choisissez les événements à recevoir ; PAYMENT_INTENT_SUCCEEDED est déjà sélectionné. L’adresse doit être publique : les adresses privées et locales sont refusées.

2. Conservez le secret

   Le tableau de bord n’affiche le secret de l’endpoint (il commence par whsec_) qu’une seule fois. Gardez-le dans l’environnement de votre serveur, jamais dans une page web.

3. Vérifiez chaque requête

   Lisez le corps brut avant tout parseur JSON et vérifiez X-Cosmos-Signature à partir de celui-ci. Avec le SDK TypeScript, Webhooks.constructEvent vérifie la signature, refuse par défaut une signature de plus de cinq minutes et renvoie l’événement.

4. Répondez vite, puis traitez

   Répondez avec un statut 2xx dès que la signature est valide, et faites ensuite le travail lent, comme les e-mails ou les mises à jour de stock.

5. Traitez chaque événement une fois

   Enregistrez l’id de chaque événement que vous traitez et ignorez ceux que vous avez déjà vus : une relance ou un renvoi transmet de nouveau le même événement.

6. Envoyez un test

   Utilisez Envoyer un test sur l’endpoint pour recevoir un événement ping, puis faites un paiement de test en Sandbox et suivez sa livraison dans la liste de l’endpoint.

Les webhooks dans le SDKPremiers pas

Quand votre serveur ne répond pas

Seule une réponse 2xx compte comme livrée, et les redirections ne sont pas suivies. Cosmos Pay relance une livraison échouée jusqu’à trois fois avec une pause croissante, puis de nouveau lors de séries ultérieures, et l’événement garde son id à chaque tentative.

Dans le tableau de bord, chaque endpoint liste ses livraisons, avec un filtre pour celles qui ont échoué, et vous pouvez renvoyer n’importe laquelle. Cosmos Pay conserve le corps d’une livraison pendant 30 jours : renvoyez-la dans ce délai.

Ou vérifiez un paiement vous-même

Vous pouvez aussi interroger un paiement précis : récupérez-le par son id pour lire son statut, ou envoyez le hash de sa transaction (sur Solana, la signature de la transaction) à POST /v1/payment-intents/:id/validate. Utilisez-le en solution de repli, par exemple quand votre client revient avant l’arrivée du webhook ; le webhook reste le signal principal.

API des intentions de paiement