Tovanix
Tovanix

Utiliser les paiements multichaînes

Le service de paiement en entier :

  • Deux voies d’intégration : la caisse (configurez-la et envoyez le lien, sans code) et l’application avec API (votre système crée les commandes et reçoit les notifications push)
  • Deux modes de garde : les fonds des adresses gardées par la plateforme sont retirables après regroupement, avec des frais prélevés au regroupement ; ceux des adresses en autogarde arrivent directement chez vous, avec des frais débités du solde du compte à chaque paiement
  • Configuration de l’application : l’App Key signe les commandes, le secret des notifications push sert à vérifier les notifications, l’URL de rappel doit être en https, réception par rotation ou en 1-à-1 au choix
  • Une notification push est livrée dès le retour d’un code 2xx ; en cas d’échec, jusqu’à 10 nouvelles tentatives automatiques, et le journal des notifications push permet de renvoyer
  • Pages des fonds : pool d’adresses, actifs, configuration du regroupement, retraits et transferts de fonds, transactions, retraits par API
  • La précision des jetons et le décalage de réception déterminent les derniers chiffres du montant dû ; plusieurs commandes sur une même adresse se distinguent par ces chiffres : le montant doit être exact

Ce que fait ce service

Les paiements multichaînes sont le service central de la plateforme : vos clients paient en USDT ou dans d’autres cryptomonnaies, et les fonds arrivent sur des adresses de réception à votre nom. Il existe deux voies d’intégration : vous pouvez n’en utiliser qu’une ou les deux à la fois.

  • Caisse : la plateforme génère un lien dédié et un code QR. Configurez marque et paramètres, puis envoyez au client, sans code.
  • Application et API : créez une application pour ses clés, puis votre système crée les commandes et reçoit les webhooks de paiement. Adapté à un système existant.

Choisir d’abord un mode de garde

Les adresses de réception sont de deux types : les adresses gardées par la plateforme et les adresses en autogarde. Le mode de garde suit l’adresse : une même application peut utiliser les deux types d’adresses. Il détermine où restent les fonds, comment les frais sont prélevés et quelles fonctions sont disponibles : décidez-en avant de commencer à encaisser.

  • Garde par la plateforme — La plateforme attribue les adresses de réception. Une fois regroupés, les fonds reçus apparaissent dans « Retirable (regroupé) », sous « Actifs » ; vous pouvez ensuite les retirer vers une adresse externe, les transférer vers le solde du compte ou les retirer par API.
  • Autogarde — Importez dans « Pool d’adresses → Adresses en autogarde » des adresses dont vous détenez vous-même la clé privée. Les fonds arrivent directement sur votre adresse : la plateforme se contente de détecter les arrivées, d’envoyer les notifications push et de tenir les comptes, sans regroupement ; vous gérez les fonds vous-même.

Les fonds des adresses en autogarde ne transitent pas par la plateforme : ils n’apparaissent pas dans « Retirable (regroupé) » et ne peuvent donc être retirés ni via la plateforme ni par API. Avant de choisir l’autogarde, vérifiez que votre processus de décaissement ne dépend d’aucune de ces deux voies.

Comment les frais sont prélevés

  • Garde par la plateforme — Au regroupement, un pourcentage est déduit du montant regroupé, avec en plus un minimum par jeton ; le reste arrive dans « Retirable (regroupé) ». Le pourcentage est le taux en vigueur sur votre compte : taux par défaut, taux individuel ou taux dégressif par paliers selon le montant déjà regroupé dans le mois.
  • Autogarde — Après chaque paiement reçu, le nombre de jetons multiplié par le taux est converti en dollars américains et débité du solde de votre compte, avec un minimum par paiement.

Les frais d’autogarde sont débités du solde du compte, qui peut devenir négatif. Tant que le solde est inférieur à 0, les applications qui reçoivent sur des adresses en autogarde n’acceptent plus de nouvelles commandes : les commandes passées par les clients échouent, celles déjà créées ne sont pas affectées, et les notifications push d’arrivée du mode 1-à-1 sont mises en attente. Dès qu’un rechargement ramène le solde au-dessus de 0, tout reprend automatiquement et les notifications mises en attente sont envoyées.

Les taux se consultent dans « Règles des frais de plateforme », sous « Actifs → Configuration du regroupement » : taux en vigueur, taux dégressifs selon le volume mensuel et frais minimum par jeton. Dans le détail d’une commande, la ligne « Frais » est la base du débit pour une adresse en autogarde ; pour une adresse gardée par la plateforme, elle n’est qu’indicative : le montant réellement prélevé est celui calculé au regroupement.

Créer une application de paiement

  • Créer l’application et enregistrer ses identifiants: Dans « Paiements multichaînes → Liste des applications », cliquez sur « Créer une application » : l’App ID et l’App Key s’affichent après la création. Vous pourrez revoir l’App Key plus tard en cliquant sur « Secret » dans la liste des applications. Une nouvelle application n’a pas encore de secret des notifications push : dans la même fenêtre, cliquez sur « Réinitialiser le secret des notifications push » pour en générer un, puis configurez-le sur votre serveur pour vérifier les signatures.
  • Définir les URL de rappel et de redirection: L’URL de rappel reçoit les notifications push des résultats de paiement et doit être une adresse https ; l’URL de redirection est la page vers laquelle le client est renvoyé après avoir payé. Leurs rôles diffèrent : ne saisissez pas la même adresse dans les deux champs.
  • Choisir un mode de paiement: La rotation attribue une adresse du pool à chaque commande ; le mode 1-à-1 lie une adresse fixe par client et notifie les arrivées. Les deux peuvent être activés ensemble.
  • Choisir les réseaux et les jetons acceptés: Ouvrez l’onglet « Configuration de l’application » dans le détail de l’application : la liste présente les réseaux et les jetons ouverts par la plateforme. Cochez ceux que cette application doit accepter, choisissez la monnaie fiduciaire dans laquelle les commandes sont libellées, puis cliquez sur « Enregistrer ».

L’App Key et le secret des notifications push sont des identifiants. Afficher le secret des notifications push en entier, le générer ou le réinitialiser exige une vérification d’identité ; si l’API ouverte est activée pour l’application, afficher ou réinitialiser l’App Key l’exige aussi. Après une réinitialisation, l’ancienne valeur cesse immédiatement de fonctionner et l’intégration en cours est interrompue : planifiez le basculement avant de réinitialiser.

Recevoir des paiements via la caisse

La caisse ne nécessite aucun code : configurez-la pour obtenir un lien dédié et un code QR à remettre aux clients. Trois onglets regroupent les réglages.

  • Paramètres de paiement — Application liée, monnaies fiduciaire et crypto par défaut, montant minimum, fenêtre de commande, URL de redirection après paiement réussi et URL de notification de paiement. La fenêtre de commande est la durée du compte à rebours de la page de paiement, réglable de 5 à 1440 minutes ; à la fin du compte à rebours, la commande est conservée 25 minutes de plus pour recueillir les paiements envoyés juste avant l’échéance et encore en cours de confirmation sur la chaîne. Si l’URL de notification de paiement est renseignée, les notifications push y sont envoyées ; sinon, elles vont à l’URL de rappel de l’application liée.
  • Identité de marque — Modèle de caisse (cinq au choix : « Minimalisme moderne », « Marque affirmée », « Compact », « Univers crypto » et « Confiance professionnelle », modifiable à tout moment), logo, nom de marque, couleur du thème, slogan et description : ils définissent ce que voit le client en ouvrant la caisse.
  • Paramètres d’affichage — Coordonnées affichées au client (e-mail, téléphone, Telegram, site officiel), possibilité pour le client d’ajouter une note à la commande, obligation ou non de laisser des coordonnées et types de coordonnées acceptés.

Si l’application liée utilise la rotation, la page le signale directement. Cette ligne indique l’origine de l’adresse de réception et n’est pas une erreur.

Commandes, commandes de caisse et journaux webhook

  • « Commandes » : toutes les commandes de paiement s’y trouvent ; celles créées par la caisse portent l’étiquette « Guichet de paiement » et se filtrent avec « Source de la commande ». Le détail d’une commande indique les informations sur la chaîne, les frais de ce paiement et l’état de la notification.
  • « Commandes du guichet de paiement » : seules les commandes créées par la caisse, filtrables par statut (en attente de paiement, payées, expirées, annulées), avec la possibilité de copier le lien de caisse de chaque commande.
  • « Journal des notifications push » : la requête, la réponse et le résultat de chaque notification push. Pour diagnostiquer une intégration, commencez ici : vous verrez si rien n’a été envoyé ou si votre serveur n’a pas accepté la notification. Toute entrée, réussie ou en échec, peut être renvoyée avec « Renvoyer ».

Règles des notifications push : la notification est considérée comme livrée dès que votre serveur renvoie un code 2xx, quel qu’il soit, dans les 10 secondes ; la plateforme ne lit pas le contenu de la réponse. Un dépassement de délai, un code autre que 2xx ou une redirection comptent comme un échec. Après un échec, la plateforme réessaie au bout de 30 secondes, 1 minute, 2 minutes et 5 minutes, puis toutes les 10 minutes, jusqu’à 10 nouvelles tentatives. Chaque notification porte un notify_id unique, identique lors des nouvelles tentatives automatiques et de « Renvoyer » : servez-vous-en pour dédupliquer.

Fonds, pool d’adresses et versements

L’emplacement des fonds dépend du mode de garde ; ces pages couvrent ses différentes étapes.

  • Pool d’adresses — Nombre total d’adresses, nombres d’adresses disponibles et liées, et actifs présents sur chaque adresse ; ajoutez à une adresse une note visible par vous seul ; déliez une adresse pour la remettre dans le pool disponible ; une adresse gardée par la plateforme peut être regroupée individuellement avec « Regrouper ». Les adresses en autogarde s’importent depuis l’entrée « Adresses en autogarde » ; les règles figurent dans la note ci-dessous.
  • Actifs — En haut, le solde du compte, « Retirable (regroupé) » et « Sur la chaîne, non encore regroupé (estimation) » sont affichés séparément. Les deux derniers ne s’additionnent pas : les fonds en attente de regroupement ne peuvent être retirés qu’après regroupement et déduction des frais. Cette page donne aussi accès au rechargement, au retrait, au transfert de fonds, aux factures de la plateforme, à l’historique et à la configuration du regroupement.
  • Configuration du regroupement — Consultez les « Règles des frais de plateforme ». Dans « Paramètres du regroupement automatique », fixez un seuil par jeton : le regroupement se déclenche automatiquement dès que le seuil est atteint, et le seuil ne peut pas être inférieur au minimum de regroupement de la plateforme. Vous pouvez aussi cliquer sur « Regrouper maintenant tous les actifs éligibles ». Un seuil plus élevé signifie moins de regroupements, donc des frais minimum appliqués moins souvent.
  • Retraits et transferts de fonds — « Retirer » envoie des actifs retirables vers une adresse externe et nécessite d’avoir activé l’authentification à deux facteurs ; la page affiche pour chaque jeton les frais, le minimum de retrait et le total déduit. Les frais sont prélevés en plus : le montant saisi arrive en totalité. Vous pouvez aussi définir des règles de retrait automatique, qui retirent dès qu’un seuil est atteint après le regroupement. « Transfert de fonds » convertit des actifs retirables en dollars américains au taux du moment et les verse sur le solde du compte, de façon irréversible.
  • Transactions — Les transactions sur la chaîne de toutes les adresses du pool. Chacune indique la commande associée ; celles qui ne correspondent à aucune commande portent « Non associé », celles pour lesquelles aucune commande n’a été créée portent « Aucune commande ».
  • API de retrait — Décaissement programmé, qui n’utilise que les actifs de « Retirable (regroupé) ». Configurez d’abord la clé publique de l’appelant et au moins une adresse IP autorisée pour pouvoir activer l’« Interrupteur principal » ; la clé API utilisée doit aussi avoir « Retraits par API » coché dans « Gestion des API ». Vous pouvez définir un délai de retrait, le mode de prélèvement des frais, une limite par retrait et une liste blanche d’adresses ; pendant le délai, vous pouvez suspendre, annuler ou traiter immédiatement un retrait dans « Historique des retraits ».

Importer des adresses en autogarde : seule l’adresse est saisie ; aucune clé privée n’est nécessaire ni acceptée. À l’import, signez avec le portefeuille de chaque adresse un texte de vérification fourni par la page, pour prouver que l’adresse vous appartient ; la signature ne dépense aucun actif et n’autorise aucun transfert, et ce texte est valable 15 minutes. Les réseaux importables sont ceux affichés sur la page ; seules les adresses TRON et EVM sont prises en charge, avec 20 adresses au maximum par import et 100 au maximum par réseau. Une adresse liée à une application en rotation ou portant encore une commande non expirée ne peut pas être supprimée ; la suppression efface aussi les transactions détectées sur cette adresse.

Configuration des jetons : précision et décalage

Deux paramètres définissent ensemble l’apparence du montant à payer pour le client.

  • Précision : nombre de décimales du montant crypto, de 2 à 10. Six sont conseillées pour USDT / USDC, deux pour TRX.
  • Décalage de réception : si une adresse a plusieurs commandes impayées en même temps, le système ajuste les dernières décimales pour les distinguer.
  • Le décalage a un type et une plage qui doit respecter la précision ; il ne peut varier que dans les décimales autorisées.

Le montant affiché doit donc être payé exactement : les derniers chiffres identifient la commande. Payer un peu plus ou moins peut empêcher son identification.

Intégration API

La référence complète se trouve dans le centre de documentation pour les développeurs : mécanisme de signature, exemples de requêtes et de réponses, codes d’erreur, événements des notifications push et vérification des signatures. L’entrée « Documentation d’intégration API » de la barre latérale de la console y mène directement.

Les requêtes de création de commande sont signées avec l’App Key ; les notifications push que la plateforme vous envoie sont signées avec le secret des notifications push, et la signature doit être vérifiée sur votre serveur. L’option « Autoriser les autres API ouvertes » du détail de l’application est désactivée par défaut : les identifiants de l’application ne peuvent alors appeler que les API de paiement et de taux de change. Une fois l’option activée, ils peuvent consulter les autres services ; les API de commande et de débit n’acceptent toujours que les clés API de « Gestion des API ».

Dépannage

  • Un client a payé, mais aucune notification n’est arrivée — URL de rappel incorrecte ou réponse du serveur inadéquate — Consultez d’abord le « Journal des notifications push ». Sans entrée, vérifiez l’URL de rappel de l’application, qui doit être une adresse https ; avec une entrée en échec, vérifiez que votre serveur a renvoyé un code 2xx dans les 10 secondes, puis, une fois le problème corrigé, cliquez sur « Renvoyer ». Vérifiez aussi que les signatures sont contrôlées avec le secret des notifications push actuel.
  • Un transfert n’a pas été associé à une commande — Le montant payé diffère du montant exact affiché — Une même adresse peut porter plusieurs commandes en attente de paiement ; le système les distingue par le décalage des derniers chiffres du montant. Il faut payer exactement le montant affiché, au centime près. Les transferts non rapprochés portent « Non associé » dans « Transactions ».
  • Aucune adresse de réception n’est attribuée — Le pool d’adresses n’a plus d’adresse libre et l’attribution automatique a atteint sa limite, ou les adresses de rotation ne comportent aucune adresse sur ce réseau — Mode 1-à-1 : quand votre pool n’a plus d’adresse libre, la plateforme en attribue automatiquement, jusqu’à 1000 par réseau toutes les 24 heures ; au-delà, déliez les adresses inutilisées ou importez vos propres adresses. Rotation : si des adresses de rotation sont configurées dans l’application, seules celles-ci sont utilisées ; vérifiez que la liste contient une adresse sur ce réseau.
  • L’API de retrait indique un solde insuffisant — Les fonds sont encore sur la chaîne en attente de regroupement, ou ont été reçus sur une adresse en autogarde — Consultez « Retirable (regroupé) » dans « Actifs ». Les fonds en attente peuvent être regroupés avec « Regrouper maintenant tous les actifs éligibles », dans « Configuration du regroupement » ; les fonds d’une adresse en autogarde ne transitent pas par la plateforme et ne peuvent pas être retirés par API.
  • Une application en autogarde n’accepte plus de nouvelles commandes — Le solde du compte est inférieur à 0 — Les frais d’autogarde sont débités du solde du compte. Dès qu’un rechargement ramène le solde au-dessus de 0, tout reprend automatiquement et les notifications push 1-à-1 mises en attente sont envoyées.
  • Une adresse 1-à-1 a reçu un très petit transfert, sans commande créée — Les arrivées d’une valeur inférieure à 0,01 dollar ne créent pas de commande — Les fonds sont bien arrivés sur l’adresse ; simplement, aucune commande n’est créée et aucune notification push n’est envoyée. Ce transfert apparaît dans « Transactions » avec l’étiquette « Aucune commande ».
  • La création d’une commande de paiement ou la liaison d’une nouvelle adresse est refusée — Le compte est restreint ou gelé — Dans cet état, vous ne pouvez ni créer de commande de paiement ni lier de nouvelle adresse ; les commandes existantes restent consultables et peuvent être clôturées. Contactez le support.

Questions fréquentes

Un client a payé, mais mon système n’a reçu aucune notification : que faire ?

Consultez d’abord le « Journal des notifications push ». Sans entrée, vérifiez que l’URL de rappel de l’application est correcte et en https ; si une notification a été envoyée mais a échoué, votre serveur n’a pas renvoyé de code 2xx dans les 10 secondes. Une fois le problème corrigé, cliquez sur « Renvoyer » sur l’entrée ; la plateforme renvoie aussi automatiquement selon son calendrier de nouvelles tentatives.

Où voir les frais et quand sont-ils prélevés ?

Le taux en vigueur se consulte dans « Règles des frais de plateforme », sous « Actifs → Configuration du regroupement ». Pour les adresses gardées par la plateforme, les frais sont prélevés au regroupement ; pour les adresses en autogarde, ils sont débités du solde du compte à chaque paiement reçu. Dans le détail d’une commande, les « Frais » ne sont qu’indicatifs pour la garde par la plateforme : le montant réellement prélevé est celui du regroupement.

Pourquoi le client doit-il payer exactement le montant affiché ?

Parce qu’une même adresse peut porter en même temps plusieurs commandes en attente de paiement, que le système distingue par le décalage des derniers chiffres du montant. Si le montant ne correspond pas, le transfert risque de ne pas être associé automatiquement à une commande.

Pages connexes: Centre d'aide · Guides et FAQ · Paiements crypto multichaînes · Documentation API

Chargement…