Intégration d’une API de paiement en cryptomonnaies : ce que votre équipe doit réellement développer

Un guide avant le lancement et une présentation vidéo étape par étape

Question {{n}} sur {{t}}

Prêt pour la mise en production

Votre équipe a répondu aux questions essentielles. Le lancement approche : effectuez vos tests avec des paiements réels avant la mise en production.

Vous y êtes presque

Il reste quelques points à régler avant le lancement : chacun est abordé dans une section de cet article.

Pas encore prêt

Plusieurs décisions essentielles restent à prendre. Hosted Checkout est la solution qui allège le plus le travail de votre équipe. Vous pouvez demander une démonstration en direct à l’équipe commerciale de Volet.com pour découvrir d’abord le parcours de paiement.

Intégration API : vérifications avant le lancement

Neuf questions à trancher avant la mise en production. Choisissez la réponse qui correspond à votre équipe : chaque réponse affiche une courte explication et renvoie à la section de cet article qui détaille le sujet.

Question 1 sur 9

1. Le produit nécessite-t-il une interface de paiement personnalisée ?

Oui, il nous faut notre propre interface

Non, une page hébergée convient

Pas encore décidé

Si oui, vous devez utiliser l’API seule, et votre équipe doit créer et maintenir les écrans de paiement. Sinon, Hosted Checkout demande moins de travail et accepte aussi les paiements à partir du solde d’un compte Volet.com.

→ Voir : API ou Hosted Checkout : comparaison pratique, ci-dessous

2. Devons-nous maîtriser chaque étape du parcours de paiement, ou une redirection est-elle acceptable ?

Nous devons maîtriser chaque étape

Une redirection convient

Pas encore décidé

Avec une redirection vers Hosted Checkout, Volet.com envoie des notifications de statut à votre URL de statut. Si vous utilisez votre propre interface de paiement avec l’API, votre backend doit vérifier lui-même le statut du paiement.

→ Voir : API ou Hosted Checkout : comparaison pratique, ci-dessous

3. Avons-nous les ressources nécessaires pour créer et maintenir l’interface de paiement, gérer les expirations et vérifier les statuts ?

Oui, nous avons les ressources

Non, Hosted Checkout nous convient mieux

Nous ne savons pas encore

Avec l’API seule, votre équipe prend en charge les écrans de paiement, l’expiration des factures (le taux d’une facture est valable 60 ou 15 minutes) et les vérifications régulières des statuts.

→ Voir : Ce que votre équipe doit concrètement développer, ci-dessous

4. Avons-nous défini comment relier les commandes internes aux tentatives de paiement et éviter qu’une commande soit exécutée plusieurs fois ?

Oui, c’est défini

Pas encore

Distinguez chaque commande de ses tentatives de paiement, utilisez un orderId unique pour chaque tentative et n’exécutez chaque commande qu’une seule fois.

→ Voir : Modèle de gestion des commandes et des paiements côté backend, ci-dessous

5. Avons-nous défini comment rapprocher les transactions du prestataire, les montants reçus, les frais et la devise de règlement ?

Oui, nous avons une procédure

Pas encore

Enregistrez pour chaque commande l’identifiant de transaction Volet.com, le montant reçu et la devise de règlement afin de pouvoir associer chaque paiement à une facture.

→ Voir : Modèle de gestion des commandes et des paiements côté backend, ci-dessous

6. Avons-nous prévu un budget pour les scénarios d’échec, les tests qualité de bout en bout et la surveillance en production ?

Oui, c’est prévu

Pas encore

Estimez séparément le travail nécessaire pour le parcours sans incident et les scénarios d’échec : la gestion des dépassements de délai, des factures expirées et des nouvelles tentatives prend du temps de développement.

→ Voir : Estimer le travail de manière réaliste, ci-dessous

7. Avons-nous décidé comment gérer les paiements insuffisants, excédentaires, tardifs ou envoyés sur le mauvais réseau ?

Oui, nos règles sont définies

Pas encore

Les paramètres de la passerelle déterminent si les paiements insuffisants et excédentaires sont acceptés. Les paiements envoyés sur le mauvais réseau peuvent être perdus. Inscrivez vos règles et votre politique de remboursement dans vos conditions de vente.

→ Voir : En quoi les paiements en cryptomonnaies diffèrent des paiements par carte, ci-dessous

8. L’équipe financière sait-elle dans quelle devise les paiements sont réglés et comment la conversion est facturée ?

Oui, l’équipe financière est informée

Pas encore

Vous pouvez conserver les cryptomonnaies reçues ou les convertir automatiquement. Les conversions entre USD, USDT et USDC se font à un taux fixe de 1:1 ; les autres conversions entraînent des frais supplémentaires.

→ Voir : Les tarifs de Volet.com, ci-dessous

9. Avons-nous prévu comment tester avec des paiements réels, sachant qu’il n’y a pas d’environnement de test ?

Oui, nous avons un plan de test

Pas encore

Volet.com ne dispose pas d’environnement de test. Demandez une démonstration en direct, créez la passerelle suffisamment tôt et testez avec des paiements réels avant le lancement.

→ Voir : Tester sans environnement de test, ci-dessous

Votre résultat

Répondez aux neuf questions pour voir votre résultat.

Points restant à régler :

 

En quoi les paiements en cryptomonnaies diffèrent des paiements par carte

Si votre équipe a déjà intégré les paiements par carte, certaines habitudes devront changer. Avec une carte, le commerçant débite le client. Avec les cryptomonnaies, le client envoie les fonds depuis son propre portefeuille, et votre système doit réagir en fonction des fonds réellement reçus. L’intégration doit donc répondre à d’autres exigences.

Le montant peut différer de celui de la facture. Un client peut envoyer un peu moins ou un peu plus que le montant demandé, par exemple en raison des frais de réseau ou d’écarts de taux de change. Décidez à l’avance si vous acceptez les paiements insuffisants ou excédentaires.

Vous pouvez, par exemple, accepter de petits écarts, contacter le client ou effectuer un remboursement. Quelle que soit votre décision, précisez-la dans vos conditions de vente, ainsi que vos règles de remboursement et la partie qui prend en charge les frais de réseau lors d’un remboursement.

Le choix du réseau compte. Un même jeton existe sur plusieurs blockchains. Les fonds envoyés via le mauvais réseau ou à la mauvaise adresse peuvent être perdus.

Le taux proposé expire. Le taux appliqué à une facture est valable pendant 60 minutes si le règlement s’effectue dans la même devise, et pendant 15 minutes si une conversion est nécessaire. Un client qui paie en retard peut avoir besoin d’une nouvelle demande de paiement.

La confirmation prend du temps. Les fonds ne sont crédités qu’après confirmation du paiement par la blockchain. Votre interface et la logique de gestion des commandes doivent donc prévoir ce délai d’attente.

Il n’y a ni rétrofacturation ni annulation automatique. Une transaction confirmée sur la blockchain ne peut pas être annulée. Un remboursement constitue un paiement distinct, soumis à votre propre politique et aux règles applicables en matière de protection des consommateurs.

Le règlement relève d’un choix de gestion. Les fonds sont crédités sur votre compte Volet.com une fois le paiement finalisé. Vous pouvez conserver les cryptomonnaies reçues ou les convertir automatiquement en stablecoins ou en monnaie fiduciaire. Votre équipe financière peut ainsi effectuer le rapprochement dans une seule devise et éviter la volatilité.


En savoir plus : Tarifs des comptes professionnels Volet.com


Ce que Volet.com prend en charge

Les confirmations du réseau sont gérées pour vous. Volet.com surveille la blockchain, attend les confirmations requises et crédite les fonds. Votre backend n’a donc pas à suivre les blocs ni à compter les confirmations.

Un solde unique en stablecoin sur plusieurs réseaux. Un stablecoin reçu sur un réseau peut être retiré via un autre réseau pris en charge, sans recourir à un service distinct de pont inter-chaînes.

Aucune réserve glissante. Volet.com ne retient aucune partie de vos paiements finalisés au titre d’une réserve glissante.

Vos règles pour les paiements insuffisants et excédentaires. Dans les paramètres de la passerelle, vous décidez d’accepter ou non les paiements inférieurs ou supérieurs au montant de la facture. Par exemple, si vos clients alimentent un solde chez vous, vous pouvez créditer le montant exact reçu et accepter les paiements insuffisants. En cas de paiement excédentaire, seul le montant de la commande est crédité sur votre compte.

Les paiements tardifs sont pris en charge. Si un paiement arrive après l’expiration de la facture, Volet.com le renvoie au client ou, dans certains cas, le crédite sur votre compte.

Encaissements et décaissements. Le même solde Volet.com peut financer vos paiements sortants : paiements de masse à des prestataires, créateurs ou partenaires, ou retraits de vos propres utilisateurs. Par exemple, une plateforme d’échange peut accepter les versements en cryptomonnaies de ses utilisateurs et traiter leurs retraits en cryptomonnaies via l’API à partir du même solde Volet.com.

Volet.com vous aide à construire vos paiements internationaux
En devises, en cryptos et en stablecoins. Via l’API, le Hosted Checkout ou des plugins faciles à installer. Encaissez, envoyez et gérez vos fonds – directement depuis votre code.

API ou Hosted Checkout : comparaison pratique

La décision clé porte sur les étapes du parcours de paiement que votre produit doit gérer lui-même — et sur l’effort de développement que vous êtes prêt à y consacrer.

Choisissez une intégration par API seule si vous avez besoin de votre propre interface de paiement et d’un contrôle sur l’ensemble du parcours de paiement. Votre application gère toutes les étapes côté client, de l’affichage des instructions de paiement à l’information du client jusqu’à la confirmation ou l’expiration du paiement. Votre équipe développe et assure la maintenance de l’ensemble.


Guides Volet.com : Intégration de l’API


Choisissez Hosted Checkout si vous n’avez besoin ni d’une interface de paiement personnalisée ni d’un contrôle total sur chaque étape. Volet.com héberge la page de paiement : cette solution est donc généralement plus simple et demande moins de travail. Elle fonctionne aussi dans les bots et les mini-applications Telegram, où la page de paiement s’ouvre dans une fenêtre de navigateur intégrée (webview).


À lire aussi : Paiements en cryptomonnaies dans les mini-applications Telegram — Guide de configuration, règles des Stars et frais réels


Vous pouvez aussi combiner Hosted Checkout avec l’API pour consulter les commandes et effectuer le rapprochement. Dans tous les cas, Hosted Checkout nécessite tout de même un travail côté backend. Votre application conserve ses propres données de commande et les rapproche du statut du paiement côté Volet.com. Votre backend signe également les requêtes qu’il envoie à Hosted Checkout, ce qui contribue à vous protéger contre les requêtes falsifiées qui pourraient détourner le paiement d’un client de votre boutique.

Critère de décisionAPI seuleHosted Checkout
Interface de paiement côté clientDéveloppée et maintenue par votre équipeHébergée par Volet.com
Contrôle du parcours de paiementÉlevé : votre application maîtrise l’expériencePlus limité : le client suit le parcours hébergé
Effort de développementPlus élevé : interface, vérifications du statut, expiration et cas limitesMoindre pour l’interface de paiement ; le backend doit toujours signer les demandes de paiement, traiter les notifications et mettre à jour les commandes
Cas d’usage idéalParcours de paiement personnalisé sur un site web ou dans une application, un bot ou une plateformeParcours de paiement standard où une redirection vers une page hébergée est acceptable, y compris dans les bots et mini-applications Telegram
Gestion des statutsLe backend vérifie le statut du paiement via l’APINotifications envoyées à l’URL de statut et consultation via l’API pour le rapprochement si nécessaire
Paiement depuis le solde d’un compte Volet.comNon disponible : l’API seule accepte les cryptomonnaies provenant de portefeuilles externesDisponible : les clients peuvent payer depuis le solde de leur compte Volet.com, avec une commission de 0,25 %
Volet.com vous aide à construire vos paiements internationaux
En devises, en cryptos et en stablecoins. Via l’API, le Hosted Checkout ou des plugins faciles à installer. Encaissez, envoyez et gérez vos fonds – directement depuis votre code.

Ce que votre équipe doit concrètement développer

Les points de terminaison de facturation ne sont qu’une partie d’une intégration reposant uniquement sur l’API. Avant de vous engager dans cette voie, tenez compte des responsabilités liées au produit et à son fonctionnement au quotidien, détaillées ci-dessous.

Déroulement du paiement avec l’API seule :

  1. Créez la commande dans votre propre système.
  2. Créez une facture en cryptomonnaie via l’API.
  3. Affichez au client l’adresse, le montant, la devise, le réseau et l’heure d’expiration renvoyés par l’API.
  4. Le client envoie le paiement depuis son portefeuille.
  5. Votre backend vérifie le statut du paiement via l’API.
  6. Une fois le paiement confirmé, marquez la commande comme payée et exécutez-la.

Déroulement du paiement avec Hosted Checkout et l’API :

  1. Créez la commande dans votre système et redirigez le client vers Hosted Checkout avec votre orderId.
  2. Le client paie sur la page Hosted Checkout.
  3. Volet.com envoie une notification à votre URL de statut, le point de terminaison de votre serveur qui reçoit les mises à jour des paiements.
  4. Votre backend vérifie la signature et, si nécessaire, confirme la commande via l’API.
  5. Marquez la commande comme payée et exécutez-la.

Interface de paiement et cycle de vie des factures. Votre application doit afficher avec exactitude les informations de paiement renvoyées par l’API : montant à envoyer, devise, réseau blockchain, adresse, éventuel tag de destination ou mémo, et heure d’expiration. Elle doit avertir les clients de n’envoyer les fonds que via le réseau indiqué. Des instructions de paiement incorrectes peuvent entraîner une perte de fonds : il s’agit donc d’une exigence fonctionnelle, pas d’un détail visuel.

N’indiquez pas au client qu’un paiement a échoué ou qu’il est terminé avant que son statut ne le confirme.

Modèle de gestion des commandes et des paiements côté backend. Conservez la commande interne séparément de toute tentative de paiement ou facture. Cela facilite la gestion des abandons de paiement, des factures expirées, des nouvelles tentatives du client et des mises à jour de statut reçues après que l’utilisateur a quitté la page.

Utilisez un orderId unique pour chaque tentative de paiement, comme l’indique la documentation de l’API. Définissez dans votre propre base de données le lien entre chaque tentative et la commande. Enregistrez l’identifiant de transaction Volet.com, le montant reçu et la devise de règlement avec chaque commande, afin que l’équipe financière puisse rapprocher chaque paiement d’une facture sans avoir à remplir manuellement des feuilles de calcul. Le traitement fiscal des recettes en cryptomonnaies dépend de votre juridiction : convenez avec votre comptable du traitement à appliquer.

Choisissez le mode de calcul du montant de la facture. Déterminez si le prix de la commande est fixé dans la devise que vous souhaitez recevoir ou si le client doit envoyer un montant fixe dans une cryptomonnaie donnée. Ce choix influe sur l’affichage des prix, le rapprochement et la manière d’expliquer le montant dû. Veillez à ce qu’il soit cohérent avec votre modèle tarifaire et comptable, et vérifiez les valeurs calculées avant de créer des factures réelles. La documentation de l’API explique comment configurer chaque option.


Guides Volet.com : Intégration de l’API


Supposons qu’un client passe une commande de €120 et paie en crypto. Votre backend doit conserver suffisamment d’informations pour rattacher le paiement effectué à la commande initiale. Pour ce paiement, il enregistrerait les éléments suivants :

  • L’identifiant de votre commande (ORD-10482) identifie l’achat dans votre système.
  • L’identifiant de transaction Volet.com (VLT-839201) relie le paiement à la transaction côté Volet.com.
  • Le montant reçu (environ 139 USDT) indique ce que le client a réellement envoyé.
  • La devise de règlement (EUR) indique la devise utilisée par votre équipe financière pour la comptabilité.
  • Le statut du paiement (définitif, confirmé par l’API) vous indique si le paiement peut être considéré comme terminé.

Pour effectuer le rapprochement, associez la transaction Volet.com à la tentative de paiement et à la commande, puis comparez l’identifiant de transaction, les montants attendu et reçu, la devise et le statut définitif du paiement. Si un paiement manque, arrive en retard ou ne correspond pas au montant attendu, signalez-le pour vérification au lieu de marquer automatiquement la commande comme payée.

Un client crée une commande, ouvre la page de paiement et envoie le montant demandé en cryptomonnaie. Avant que la blockchain ne confirme la transaction, il ferme l’onglet du navigateur et quitte votre site.

Votre backend continue de suivre le paiement :

  1. La commande du client reste en attente dans votre système.
  2. La tentative de paiement se poursuit indépendamment. Avec une intégration par API seule, votre backend vérifie son statut via l’API. Avec Hosted Checkout, Volet.com envoie une notification à votre URL de statut.
  3. Votre backend vérifie le statut du paiement via l’API.
  4. Une fois la finalisation du paiement confirmée, votre système marque la commande comme payée et déclenche son exécution.
  5. Si le client revient sur votre site, il voit le statut actualisé de sa commande.

À retenir : fermer la page de paiement n’annule ni ne confirme le paiement. C’est votre backend, et non la redirection du navigateur, qui détermine quand la commande peut être exécutée.

Gestion des statuts et reprise après incident. Avec l’API seule, votre équipe doit choisir une stratégie d’interrogation périodique (la fréquence à laquelle le backend vérifie le statut), éviter les requêtes inutiles et gérer les échecs temporaires de consultation sans modifier à tort l’état de la commande.

Considérez une notification comme un signal, et non comme une preuve de paiement : vérifiez sa signature et consultez la commande via l’API avant de l’exécuter. N’exécutez chaque commande qu’une seule fois, en vous appuyant sur votre propre orderId, pour qu’une notification répétée ou une seconde vérification du statut ne puisse pas déclencher une double exécution.

N’exécutez une commande qu’après confirmation par l’API que le paiement est terminé, et non dès la création de la facture ou la redirection du navigateur. La documentation de l’API décrit les valeurs exactes des statuts et la manière de traiter chacun d’eux.


Guides Volet.com : Intégration de l’API


Une requête peut dépasser le délai d’attente même si le système distant l’a traitée. Ne relancez pas aveuglément la création d’une facture après un échec dont l’issue est incertaine. Avant de décider de la suite, consignez dans les journaux l’errorId renvoyé par l’API, vérifiez l’état de la commande et du paiement existants, puis suivez la procédure de gestion des erreurs décrite dans la documentation. Ne créez jamais automatiquement une commande en double et ne relancez une requête que si cela ne présente aucun risque.

Sécurité et préparation opérationnelle. Conservez les secrets de l’API et les identifiants d’authentification sur le serveur. Ne les exposez jamais dans le code frontend, les applications mobiles, les bots ou les scripts côté client. N’accordez que les autorisations nécessaires à l’intégration et limitez l’accès à l’API aux adresses IP de vos serveurs : autoriser toutes les adresses IP est déconseillé en production.

Concevoir un parcours de paiement fiable

Un parcours de paiement ne doit pas se limiter au cas où tout se passe bien.

Définissez le comportement du produit lorsque :

  • la création d’une facture dépasse le délai d’attente et son résultat reste inconnu ;
  • la consultation d’un statut échoue temporairement ;
  • une facture expire avant que le client ne paie ;
  • le client abandonne le parcours de paiement, puis revient ;
  • le client lance une nouvelle tentative de paiement ;
  • une notification de statut arrive en retard ou est reçue plusieurs fois.

L’objectif est d’éviter la double exécution des commandes, de maintenir la cohérence de leur état interne et d’indiquer clairement au client la prochaine étape.


Guides Volet.com : Guide de l’API avec les définitions exactes des statuts et les champs de réponse


Tester sans environnement de test

Volet.com ne propose ni bac à sable ni environnement de test. Tenez-en compte dès le départ plutôt que de le découvrir au lancement :

  • Demandez une démonstration en direct à l’équipe commerciale de Volet.com pour découvrir le parcours de paiement, l’API et Hosted Checkout avant de commencer le développement.
  • Créez la passerelle suffisamment tôt. Toute nouvelle passerelle avec conservation des fonds (où Volet.com conserve les fonds reçus sur votre compte) fait l’objet d’un contrôle de conformité qui prend généralement quelques heures. Vous pouvez terminer l’intégration pendant ce temps.
  • Testez avec de vrais paiements en production : réussite, échec, expiration, paiement insuffisant et paiement excédentaire. Chaque paiement de test en cryptomonnaie est une véritable transaction sur la blockchain, soumise à des frais de réseau.
  • Pour Hosted Checkout, vérifiez également la réception des notifications à l’URL de statut, la validation des signatures et les redirections en cas de réussite ou d’échec.
  • Identifiez les commandes de test dans votre base de données pour ne pas les confondre avec les revenus réels lors du rapprochement.

Estimer le travail de manière réaliste

La charge de travail réelle dépend de votre architecture de paiement existante, de l’expérience utilisateur attendue, de l’expérience de vos développeurs avec les API de paiement et de l’étendue des tests d’assurance qualité (QA).

Volet de travailAPI seuleHosted Checkout
Configuration du compte et de la passerelleVérification du compte, configuration de l’API, autorisations et approbationVérification du compte, configuration de Hosted Checkout et toute approbation requise
Développement principalCréation des factures, interface de paiement, vérification des statuts et mise à jour des commandesParcours de redirection, gestion de l’URL de statut et mise à jour des commandes côté backend
Cas limitesExpiration, dépassements de délai au résultat incertain, nouvelles tentatives, tentatives en double et consignes sur le réseau à utiliserValidation des notifications, cas limites liés aux redirections et rapprochement
Assurance qualitéAffichage des informations de paiement, vérification du statut, expiration, échecs et repriseRedirections, réception des notifications, validation des signatures et rapprochement
Prise en charge au quotidienMaintenance de l’interface utilisateur, surveillance, diagnostics pour l’assistance et gestion des statutsSurveillance du backend, rapprochement des commandes et gestion des appels de notification

Estimez séparément le travail nécessaire pour le parcours sans incident et les scénarios d’échec, et prévoyez du temps pour les tests de bout en bout et la surveillance en production.

Les tarifs de Volet.com

À partir de 0,25 % pour les paiements en stablecoins et en cryptomonnaies. Les conversions entre USD, USDT et USDC s’effectuent à un taux fixe de 1:1 ; les autres conversions font l’objet d’une tarification distincte. Le client paie les frais du réseau blockchain. Pas de frais de mise en service ni de frais mensuels. Vous choisissez qui paie les frais de traitement. Les volumes élevés peuvent bénéficier d’une tarification personnalisée auprès de l’équipe commerciale.

Acceptez l’USDT, l’USDC et les principaux tokens crypto partout dans le monde
Commencez avec la passerelle de paiement crypto : règlements instantanés et frais à partir de 0,25%

Questions fréquentes

Non. Volet.com ne dispose pas d’environnement de test. Vous pouvez demander une démonstration en direct à l’équipe commerciale. Avant le lancement, testez de votre côté les paiements réussis, les échecs, l’expiration des factures et les montants insuffisants ou trop élevés.

Les nouvelles passerelles avec conservation des fonds font d’abord l’objet d’un contrôle de conformité. Celui-ci prend généralement quelques heures. Votre compte doit être vérifié avant la création de la passerelle. Profitez de ce délai pour terminer l’intégration.

Non. Avec une intégration API seule, votre backend vérifie lui-même le statut du paiement. Si vous avez besoin de notifications, utilisez Hosted Checkout avec l’API.

Les paramètres de votre passerelle déterminent si les paiements d’un montant insuffisant ou trop élevé sont acceptés. Si un paiement arrive après l’expiration de la facture, Volet.com le renvoie au client ou, dans certains cas, le crédite sur votre compte. Un client qui souhaite toujours payer peut avoir besoin d’une nouvelle demande de paiement.

Avant de répondre, recherchez la commande via l’API à l’aide de votre orderId.

Un transfert peut être visible sur la blockchain sans pour autant correspondre à la facture : son montant peut être insuffisant, il peut être arrivé en retard ou avoir été envoyé via un autre réseau.

Donnez à votre équipe d’assistance accès aux détails du paiement et définissez à l’avance dans quels cas elle doit transmettre le dossier à l’assistance Volet.com.

Non. Une transaction confirmée sur la blockchain ne peut pas être annulée et il n’existe pas de procédure de rétrofacturation comme sur les réseaux de cartes. Un remboursement constitue un paiement distinct, soumis à votre propre politique et aux règles applicables en matière de protection des consommateurs.

Non. Volet.com ne propose pas de service d’acquisition de paiements par carte. Conservez votre prestataire d’acquisition pour les paiements directs par carte.