Intégrer un checkout stablecoin dans votre boutique en ligne
Intégrez un checkout stablecoin dans votre boutique : comment utiliser le widget intégré, création de paiement navigateur et serveur, et vérification webhook.
Intégrer un checkout stablecoin revient à placer une fenêtre de paiement USDT ou USDC à l'intérieur de votre boutique en ligne. Le widget checkout intégré de Qvard accepte les stablecoins dès aujourd'hui. Vos clients choisissent l'actif crypto et le réseau sur la page de paiement, et vous vérifiez le paiement par webhook.
Ce qu'est un checkout stablecoin intégré
Un checkout stablecoin intégré est une fenêtre de paiement qui s'ouvre sur votre page via un widget JavaScript. Elle peut apparaître en modal (fenêtre surgissante) ou intégrée dans un élément. Vos clients restent sur votre page et paient en USDT ou USDC sans partir. La fenêtre de paiement est la même page Qvard dans une iframe : le client la voit dans sa langue, choisit l'actif stablecoin et le réseau, et le montant est calculé à un taux fixe pour votre facture.
Comment cela fonctionne chez Qvard
Le widget charge depuis https://qvard.com/checkout.js et ouvre une fenêtre de paiement stablecoin en modal ou intégrée. La fenêtre affiche les actifs et réseaux disponibles ; le client choisit, et le montant à envoyer s'affiche. Le widget émet des événements : onSuccess (paiement réussi), onClose (fenêtre fermée), onError (paiement échoué). Une instance du widget reçoit votre clé publique (qvard_pk_...) pour création côté navigateur, ou l'id du paiement pour création côté serveur. Essayez sur la page de démo chez qvard.com.
Deux façons de créer le paiement
Côté navigateur : passez la clé publique (qvard_pk_...) et le montant au widget ; il crée le paiement et ouvre la fenêtre. Le client peut modifier le montant dans le navigateur, utilisez donc ceci à titre informatif. Votre clé publique peut être limitée aux sites autorisés dans votre tableau de bord, et les requêtes sont limitées en fréquence. Côté serveur : votre backend crée le paiement via POST /api/v1/payment et passe l'id du paiement au widget. Pour les commandes avec montants fixes ou critiques, utilisez la création côté serveur et vérifiez toujours le montant dans votre webhook. Ou ignorez le widget et redirigez les clients vers la page de paiement hébergée.
Côté serveur : créez le paiement en premier
Votre serveur envoie une requête POST à /api/v1/payment avec l'id de commande et le prix en USD, en utilisant l'en-tête x-api-key avec votre clé secrète (qvard_sk_...). La réponse retourne { id, redirectUrl }. Passez l'id au widget dans le navigateur, ou utilisez redirectUrl pour une redirection. Gardez votre clé secrète sur le serveur ; la requête ne doit pas être faite depuis le navigateur.
x-api-key: qvard_sk_…
{
"id": "order_1024",
"price": 149.99,
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}Vérifiez le paiement depuis le webhook
Quand le statut est paid, votre webhook reçoit { id, status }, signés avec l'en-tête X-Qvard-Signature au format t=...,v1=... (HMAC-SHA256 avec votre clé secrète). Vérifiez la signature en utilisant votre clé secrète (qvard_sk_...) et assurez-vous que le montant dans le webhook correspond à votre commande. Les clés héritées sans le préfixe qvard_sk_ reçoivent également l'en-tête x-api-key. Marquez la commande comme payée seulement après vérification de la signature. Voir le guide de signature dans la documentation Qvard.
Quand choisir la fenêtre intégrée
Utilisez le widget modal intégré ou intégré pour garder les clients sur votre page et offrir un checkout stablecoin sans problème. La page hébergée avec redirection fonctionne tout aussi bien et est une option si vous préférez ne pas intégrer la fenêtre de paiement. Les deux partagent le même processus de création de paiement, flux webhook et vérification de signature.
FAQ
Puis-je intégrer un checkout stablecoin dans ma boutique dès aujourd'hui ?
Oui. Chargez le widget depuis https://qvard.com/checkout.js et passez votre clé publique (qvard_pk_...) pour création côté navigateur, ou créez le paiement côté serveur et passez l'id.
Comment les clients choisissent-ils un stablecoin et un réseau sur le widget ?
Les clients voient les actifs stablecoin et réseaux disponibles sur la page de paiement et choisissent celui à utiliser. Le montant à envoyer se met à jour en fonction de leur sélection.
Pourquoi dois-je vérifier le montant dans le webhook ?
Le montant dans le webhook est la source de vérité de Qvard. Vérifiez toujours qu'il correspond à votre commande, même si vous avez créé le paiement côté serveur, car le client a choisi le stablecoin et le réseau.
Comment tester avant le lancement ?
Utilisez la page de démo chez qvard.com pour tester le widget et voir les événements webhook. Confirmez que votre webhook vérifie la signature et marque la commande comme payée.
