Intégrer l’USDC au paiement en ligne

La structure d’API standard

Les API d’acquisition en USDC suivent globalement le modèle d’intention de paiement popularisé par Stripe. Le périmètre minimal :

1. 1

   Le serveur crée l’intention de paiement

   POST /v1/payments avec un corps contenant amount, currency (USD si le prix est exprimé en monnaie fiduciaire ; USDC s’il est exprimé en stablecoin), settlement_preference (USDC ou monnaie fiduciaire), networks (liste des réseaux autorisés), order_id (votre clé d’idempotence), success_url, cancel_url et un objet metadata pour votre propre rapprochement.

2. 2

   L’acquéreur renvoie une URL de paiement ou une configuration de widget

   Pour la page de paiement hébergée : une URL vers laquelle l’acheteur est redirigé. Pour le widget intégré : une configuration côté client (clé publiable, identifiant de l’intention) que le widget charge. Les deux parcours gèrent la détection du portefeuille, le choix du réseau et l’affichage de la cotation.

3. 3

   L’acheteur signe dans son portefeuille, le transfert on-chain est diffusé

   Sur mobile : lien profond (deep link) vers MetaMask, Phantom, Trust, etc. Sur ordinateur : QR code WalletConnect ou fenêtre d’extension de navigateur. L’acheteur vérifie le montant et signe.

4. 4

   L’acquéreur attend les confirmations et déclenche le webhook

   POST your_webhook_url avec une charge utile contenant event_type: “payment.succeeded”, order_id, amount, tx_hash, network et une signature que vous vérifiez avec le secret de webhook de l’acquéreur.

5. 5

   Le serveur marque la commande comme payée de manière idempotente

   Vérifiez la signature du webhook, recherchez (order_id, tx_hash) dans votre base de données, marquez la commande comme payée si ce n’est pas déjà fait, puis lancez l’exécution de la commande.

Le choix du réseau

Le choix des réseaux acceptés est un arbitrage entre expérience utilisateur et coût :

• Solana : frais de réseau inférieurs au centime, confirmation en moins d’une seconde. Le meilleur choix par défaut pour un petit panier moyen.
• Base : quelques centimes de frais de réseau, confirmation en quelques secondes. Large prise en charge par les portefeuilles ; un bon choix par défaut pour un public nativement crypto.
• Polygon, Arbitrum : frais et vitesse comparables à ceux de Base. Les ajouter ne pose pas de problème, sans être strictement nécessaire.
• Mainnet Ethereum : $1–$8+ de frais de réseau selon le gas. Pénible pour les acheteurs sur les petites commandes. À accepter pour les paniers moyens élevés (au-delà de $500) ou en solution de repli.
• Tron : si vous ciblez les flux d’USDT en Asie et en Afrique, il vaut la peine d’envisager la prise en charge de l’USDT sur TRON en plus de l’USDC.

L’idempotence des webhooks

Les webhooks font l’objet de nouvelles tentatives. Votre gestionnaire doit être idempotent. Le schéma standard :

1. Vérifiez la signature du webhook par HMAC-SHA256 avec le secret de votre acquéreur.
2. Extrayez (order_id, tx_hash) de la charge utile.
3. Recherchez cette paire dans votre table processed_payments.
4. Si elle existe : renvoyez 200 OK sans rien faire d’autre.
5. Si elle n’existe pas : insérez la ligne (avec une contrainte UNIQUE sur la paire), puis marquez la commande comme payée dans votre table principale des commandes, puis lancez l’exécution de la commande.
6. Regroupez les opérations de l’étape 5 dans une seule transaction de base de données, afin qu’un plantage en cours de traitement n’entraîne pas une double exécution.

La plupart des webhooks d’acquisition incluent un identifiant de livraison : journalisez-le pour le débogage, mais ne l’utilisez pas comme clé d’idempotence. Les confirmations réseau et les nouvelles tentatives de l’acquéreur peuvent produire des événements payment.succeeded en double, avec des identifiants de livraison différents mais le même tx_hash ; votre dédoublonnage doit reposer sur l’identité on-chain, et non sur la livraison.

Le parcours de remboursement

Deux modèles dominent :

• Remboursement à l’expéditeur : l’acquéreur renvoie les USDC à l’adresse depuis laquelle l’acheteur a payé à l’origine. C’est l’expérience la plus simple ; elle fonctionne parce que l’enregistrement on-chain du paiement contient l’adresse source.
• Remboursement vers une adresse indiquée : l’acheteur indique une adresse de destination pour le remboursement (qui peut différer de l’adresse source s’il a payé depuis une plateforme d’échange ou un hot wallet). La plupart des acquéreurs le permettent via un POST /v1/refunds avec destination_address.

Le commerçant paie les frais de réseau du remboursement. Les remboursements totaux comme partiels sont pris en charge. Le remboursement lui-même prend le même temps de confirmation on-chain que le paiement initial.

Les défaillances en production

• L’acheteur abandonne après avoir signé. Le transfert on-chain est diffusé, mais il ferme l’onglet avant que le webhook ne soit déclenché. L’acquéreur détecte et confirme tout de même le paiement grâce à sa surveillance on-chain ; l’exécution de votre commande part du webhook, et non de la redirection.
• L’acheteur paie un montant erroné. La plupart des acquéreurs rejettent les montants qui ne correspondent pas au moment de la détection on-chain. Certains acceptent des correspondances approximatives (dans une marge de tolérance) et signalent l’écart dans le webhook.
• L’acheteur paie sur le mauvais réseau. S’il signe sur Ethereum alors que vous n’acceptez que Solana, le paiement échappe entièrement à la surveillance de votre acquéreur. La plupart des prestataires restituent les fonds via une procédure de récupération ; certains les perdent. Rendez le choix du réseau clair au moment du paiement.
• L’acheteur paie depuis une adresse de plateforme d’échange. Un remboursement à l’adresse source peut être rejeté ou arriver sur le mauvais compte. Collectez explicitement une adresse de destination pour les remboursements lors du paiement, pour tout produit susceptible d’être remboursé.
• Perte de parité d’un stablecoin (depeg). Rare, mais réelle. Si l’USDC perd sensiblement sa parité pendant le bref intervalle entre la cotation et le règlement on-chain, c’est le commerçant ou l’acquéreur qui absorbe la différence, selon le contrat.