API de passerelle de paiement crypto : factures, webhooks, versements, marque blanche

À quoi sert une API de passerelle de paiement crypto ?

L'API masque la blockchain à votre code. Au lieu d'exploiter des nœuds, de dériver des adresses et de compter les confirmations, vous appelez un point d'accès pour créer une facture, conservez l'identifiant de la passerelle et attendez les notifications. La passerelle fixe le taux de change, surveille les réseaux, applique le filtrage LCB-FT et règle sur votre solde.

La plupart des passerelles exposent les mêmes briques sous des noms différents : factures ou commandes pour les paiements entrants, IPN ou callbacks pour les notifications, points d'accès de conversion et de solde, et versements ou retraits pour les transferts sortants. Des sandboxes existent chez la plupart des prestataires, par exemple un hôte sandbox distinct chez CoinGate et un compte sandbox chez NOWPayments, et doivent servir avant tout test sur le mainnet.

• API de factures : créer, lire et annuler des demandes de paiement avec prix en monnaie fiduciaire, actifs acceptés, référence de commande et URL de callback
• Notifications : webhooks ou IPN à chaque changement de statut, en général signés
• API de versements : envoyer de la crypto ou de la monnaie fiduciaire à des clients, partenaires ou à votre propre portefeuille
• Taux et devises : lister les actifs, réseaux et montants minimums pris en charge, et les cotations en direct
• Plugins et SDK : modules prêts à l'emploi pour les plateformes e-commerce, bâtis sur la même API

Comment fonctionne le cycle de vie d'une facture ?

Chaque passerelle a son propre modèle de statuts : ramenez-les à un petit ensemble interne avant d'écrire la logique métier. Seul un statut final « payé » doit libérer les marchandises ; les statuts intermédiaires existent parce qu'une transaction peut être visible sur la blockchain bien avant de pouvoir être acceptée en toute sécurité.

Le tableau fait correspondre deux modèles de statuts publiés aux états dont la plupart des plateformes ont besoin. CoinGate, par exemple, fait expirer une facture impayée après 20 minutes une fois l'actif choisi par l'acheteur, et marque comme invalides les paiements signalés par les contrôles LCB-FT.

Comment vérifier les webhooks et IPN crypto ?

Considérez chaque notification comme non fiable tant qu'elle n'est pas vérifiée. Les passerelles emploient des schémas différents : NOWPayments signe le corps JSON trié en HMAC-SHA512 et l'envoie dans l'en-tête x-nowpayments-sig, CoinGate envoie un jeton que vous définissez sur la commande, et BitPay recommande de relire la facture via l'API après chaque notification plutôt que de se fier à son contenu.

Le schéma le plus sûr combine les deux : vérifier la signature, puis lire la facture via l'API et agir sur cette réponse. Cela coûte une requête par changement de statut et protège contre les callbacks falsifiés ou rejoués.

• Vérifier les signatures par une comparaison en temps constant et rejeter les requêtes non signées
• Relire la facture par son identifiant chez la passerelle avant de modifier l'état de la commande
• Renvoyer rapidement HTTP 200 et traiter de façon asynchrone ; les passerelles réessaient en cas d'erreur
• Enregistrer chaque notification avec son événement ou statut pour ignorer les doublons
• Ne jamais se fier aux montants ni aux devises transmis dans la redirection du navigateur

Comment gérer sous-paiements, surpaiements et paiements tardifs ?

Les portefeuilles et exchanges déduisent des frais de retrait et les clients recopient mal les montants : un paiement exact ne peut pas être présumé. Définissez une tolérance et une règle pour chaque cas avant le lancement, et rendez le résultat visible pour le support.

Comment fonctionnent l'idempotence et le rapprochement ?

Créez les factures avec votre propre référence de commande et rendez l'appel rejouable sans risque : si la requête expire, cherchez la facture par référence avant d'en créer une autre, ou utilisez une clé d'idempotence quand la passerelle en propose une. La même règle vaut pour les versements, où une requête en double envoie deux fois de l'argent réel.

Pour le rapprochement, conservez l'identifiant de facture de la passerelle, le hash de transaction, le montant en monnaie fiduciaire, le montant en crypto, le taux et les frais. Les relevés de règlement présentent les versements par lots : le rapprochement va donc de la commande à la facture puis au versement, et non de la commande à la ligne bancaire.

Que doit prévoir une API de versements au regard de la règle de voyage ?

Les points d'accès de versement envoient de la crypto depuis le solde de votre passerelle vers une adresse, souvent par lots pour des commissions d'affiliés, des vendeurs de places de marché ou des retraits de clients. La plupart exigent une liste blanche d'adresses, une approbation à deux facteurs ou une clé d'API avec des droits de versement distincts.

Dans l'UE, le règlement (UE) 2023/1113 impose à la passerelle de transmettre les informations sur le donneur d'ordre et le bénéficiaire avec chaque transfert et de vérifier la propriété des portefeuilles non hébergés au-delà de 1 000 €. Prévoyez que les demandes de versement comportent le nom du bénéficiaire et le type d'adresse, et que certains transferts attendent ces données.

Quelles options de passerelle de paiement crypto en marque blanche ?

Les plateformes qui revendent des paiements à leurs propres commerçants veulent souvent la page de paiement à leur marque. Il existe trois niveaux, et le prix monte avec le contrôle. Plisio, par exemple, affiche 0,5 % pour son API et 1,5 % pour la marque blanche, et NOWPayments vend un produit de marque blanche distinct.

La marque blanche complète déplace la responsabilité autant que l'image. Si vous intégrez des commerçants et détenez leurs soldes, il se peut que vous ayez besoin de votre propre agrément MiCA ; un modèle de sous-commerçants chez une passerelle agréée laisse cette obligation à la passerelle.

Comment connecter des API de passerelles crypto avec OrsunPay ?

OrsunPay normalise les statuts, webhooks et remboursements des passerelles crypto dans une seule API, à côté de vos prestataires de cartes et de paiements bancaires, avec vos propres comptes de passerelle. OrsunPay ne conserve pas de crypto et n'effectue pas de versements depuis son propre solde : il achemine les requêtes vers la passerelle choisie et renvoie des événements signés et dédupliqués.

Comment intégrer l'API d'une passerelle de paiement en cryptomonnaie

1. Ouvrir des comptes sandbox Créez un compte sandbox et un compte de production chez la passerelle, générez des clés d'API distinctes pour les factures et les versements, et définissez le secret IPN.
2. Faire correspondre les statuts Traduisez les statuts de la passerelle en états internes et décidez lequel libère les marchandises.
3. Créer les factures de façon idempotente Envoyez montant en monnaie fiduciaire, devise, référence de commande et URL de callback ; cherchez par référence avant de relancer un appel arrivé à expiration.
4. Vérifier les notifications Contrôlez la signature, relisez la facture via l'API et traitez l'événement une seule fois.
5. Gérer les cas limites Mettez en œuvre la tolérance, le complément, le remboursement et l'expiration, et testez chacun dans le sandbox.
6. Rapprocher les règlements Conservez hash de transaction, taux et frais par facture et rapprochez chaque jour les lots de versements des commandes.