Comment intégrer une passerelle de paiement crypto White Label avec OxaPay

Intégrer une passerelle de paiement crypto White Label ne consiste pas seulement à se connecter à une API. Cela signifie ajouter un flux de paiement crypto complet à votre site web ou application tout en gardant le contrôle de l’expérience client.

Avec OxaPay White Label, votre entreprise peut afficher l’adresse de paiement, le QR code, le montant, le réseau et le statut du paiement dans sa propre interface. Pendant ce temps, OxaPay gère l’infrastructure de paiement sous-jacente, notamment la génération des paiements, la surveillance de la blockchainet les mises à jour des transactions.

Cette approche permet aux entreprises de proposer des paiements en cryptomonnaies sous leur propre marque sans construire ni maintenir en interne une infrastructure de paiement blockchain.

Dans ce guide, nous expliquons comment intégrer la passerelle White Label d’OxaPay, ce dont votre entreprise a besoin avant de commencer et quelles situations de paiement doivent être prises en compte avant la mise en production.

Le White Label convient-il à votre entreprise ?

Avant de commencer l’intégration, il est important de déterminer si une solution White Label est le bon choix pour votre flux de paiement.

Une page de paiement crypto hébergée suffit souvent aux entreprises qui souhaitent commencer à accepter rapidement les cryptomonnaies. Dans ce modèle, les clients sont redirigés vers une page de paiement fournie par la passerelle pour finaliser la transaction.

Le White Label est plus adapté lorsque l’expérience de paiement constitue une partie importante de votre produit ou du parcours client. Au lieu de rediriger les clients vers une page de paiement externe, vous affichez les informations de paiement directement dans votre site web, application, plateforme ou checkout.

Cette solution est particulièrement utile pour les entreprises qui souhaitent :

• maintenir une image de marque cohérente pendant tout le checkout
• garder les clients dans leur propre plateforme
• contrôler la manière dont les instructions et statuts de paiement sont affichés
• relier les paiements crypto à leur processus de commande existant
• éviter de construire une infrastructure de paiement blockchain à partir de zéro

La principale différence réside dans le niveau de contrôle. Votre entreprise gère l’expérience côté client, tandis qu’OxaPay gère l’infrastructure de paiement en arrière-plan.

Ce dont vous avez besoin avant de commencer

Une intégration White Label nécessite une certaine préparation, mais votre entreprise n’a pas besoin d’exploiter des nœuds blockchain ni de construire son propre système de suivi des transactions.

Votre site web ou application doit disposer d’un backend capable de communiquer de manière sécurisée avec l’ API OxaPay, de stocker les informations de paiement et de relier chaque paiement à la bonne commande.

Vous avez également besoin d’un endpoint de callback capable de recevoir les mises à jour de paiement d’OxaPay. Ces mises à jour permettent à votre système de savoir quand un client a commencé à payer et quand le paiement est terminé.

Enfin, votre interface de paiement doit pouvoir afficher des informations essentielles telles que :

• le montant du paiement
• la cryptomonnaie sélectionnée
• le réseau blockchain
• l’adresse de paiement
• le QR code
• le temps de paiement restant
• le dernier statut du paiement

L’interface doit présenter clairement ces informations, en particulier le réseau sélectionné et le délai d’expiration, car des erreurs dans ces domaines peuvent entraîner des problèmes de paiement.

Intégration d’une passerelle de paiement crypto White Label avec OxaPay

1. Créer un compte marchand OxaPay

La première étape consiste à créer un compte OxaPay et à accéder au tableau de bord marchand.

Depuis le tableau de bord, vous pouvez gérer votre clé API Merchant, les paramètres de paiement, les devises prises en charge, les enregistrements de transactions et d’autres outils marchands.

À ce stade, vous préparez votre compte professionnel à communiquer avec OxaPay. Vous n’avez pas besoin de créer des portefeuilles blockchain individuels pour chaque commande ni de construire votre propre système de surveillance des transactions.

2. Générer votre clé API Merchant

Ensuite, générez une Merchant API Key depuis votre compte OxaPay.

Cette clé permet à votre système d’authentifier les demandes de paiement envoyées à l’API OxaPay. Elle doit toujours être stockée de manière sécurisée sur votre serveur backend.

La clé API Merchant ne doit jamais être placée dans le code frontend, des dépôts publics, des scripts de navigateur ou tout autre emplacement accessible aux clients.

Votre backend doit utiliser la clé lors de la création de demandes de paiement White Label. Le frontend ne doit recevoir que les informations de paiement nécessaires à l’affichage pour le client.

3. Créer une demande de paiement White Label

Pour générer un paiement White Label, votre système envoie une requête à l’endpoint suivant :

POST https://api.oxapay.com/v1/payment/white-label

Les deux champs de paiement obligatoires sont :

• Montant: la valeur du paiement
• pay_currency: la cryptomonnaie utilisée pour le paiement

D’autres champs peuvent être ajoutés selon votre flux de paiement.

Par exemple :

• currency définit la devise utilisée pour fixer le prix de la commande, par exemple USD.
• Réseau sélectionne le réseau blockchain lorsque la cryptomonnaie est disponible sur plusieurs réseaux.
• order_id relie le paiement à une commande dans votre propre système.
• callback_url indique à OxaPay où envoyer les mises à jour de paiement.
• lifetime définit la durée pendant laquelle le paiement reste valide.
• under_paid_coverage définit l’écart acceptable entre le montant demandé et le montant reçu.

Le guide currency, Réseau, order_id, ainsi que callback_url sont facultatifs dans l’API. Cependant, l’utilisation d’un identifiant de commande et d’une URL de callback est fortement recommandée pour les entreprises qui ont besoin d’un suivi fiable des commandes.

Lorsque la requête aboutit, OxaPay crée une session de paiement et renvoie les informations dont votre système a besoin pour présenter le paiement.

4. Recevoir les informations de paiement et les afficher

Après la création de la demande de paiement, OxaPay renvoie des informations de paiement structurées.

Cela peut inclure :

• un track_id
• le montant exact du paiement
• la cryptomonnaie du paiement
• le réseau blockchain
• l’adresse de paiement
• un QR code
• l’heure d’expiration

Votre système doit stocker le track_id et le relier à la bonne commande interne. Cet identifiant aide votre entreprise à suivre le paiement et à l’examiner ultérieurement si nécessaire.

Votre frontend peut ensuite utiliser les informations renvoyées pour créer une page de paiement à votre marque.

Le client doit pouvoir :

• scanner le QR code
• copier l’adresse de paiement
• copier le montant exact
• voir la cryptomonnaie et le réseau requis
• voir combien de temps il reste
• suivre le statut actuel du paiement

C’est le principal avantage du modèle White Label. Le client effectue le paiement dans une expérience conçue et personnalisée par votre entreprise.

La page de paiement doit également avertir les clients de ne pas envoyer de fonds après l’expiration du paiement. Selon la documentation OxaPay, les adresses White Label générées ne sont valides que pendant la durée de paiement spécifiée.

5. Suivre le statut du paiement

Une fois que le client envoie la cryptomonnaie, OxaPay surveille le paiement et signale sa progression.

Statuts de paiement OxaPay peuvent inclure des états tels que :

• en attente de paiement
• paiement en cours
• paid
• underpaid
• expired
• accepté manuellement
• refunded

Votre entreprise n’a pas besoin d’afficher chaque statut interne au client. L’interface peut traduire ces états en messages simples tels que « En attente de paiement », « Paiement détecté », « Paiement terminé » ou « Paiement expiré ».

Le point important est que votre système ne doit pas finaliser la commande trop tôt.

OxaPay envoie une mise à jour paying lorsque l’activité de paiement a été détectée. Votre système doit normalement attendre le statut final paid avant de livrer le produit, d’activer le service ou de marquer la commande comme terminée.

6. Recevoir et valider les mises à jour de paiement

OxaPay envoie les mises à jour de paiement à l’ callback_url inclus dans la demande de paiement.

Ces notifications permettent à votre système de :

• identifier le paiement concerné
• mettre à jour le statut interne de la commande
• informer le client de la progression
• finaliser la commande après un paiement réussi

Comme l’endpoint de callback est accessible publiquement, votre système doit valider les notifications entrantes avant d’agir.

OxaPay fournit une signature de sécurité avec ses callbacks. Votre équipe technique doit vérifier cette signature et confirmer que les informations de paiement correspondent aux détails de commande enregistrés.

Cela n’a pas besoin d’être visible par le client, mais c’est une partie importante de la protection du processus de paiement.

Votre système doit également être prêt à recevoir plusieurs fois la même mise à jour. Un callback répété ne doit pas entraîner une livraison de produit en double, un crédit de solde répété ou plusieurs confirmations de commande.

OxaPay peut réessayer un callback lorsque votre système ne confirme pas correctement sa réception.

Gestion des sous-paiements

Il arrive qu’un client envoie un montant inférieur au montant demandé.

OxaPay propose une option de tolérance aux sous-paiements qui permet au marchand de définir un écart acceptable entre les montants attendu et reçu.

Si la différence se situe dans la plage acceptée, le paiement peut continuer selon la politique configurée. Si le montant est inférieur au seuil accepté, le paiement peut nécessiter une autre action.

Selon votre modèle économique, vous pouvez :

• demander au client de compléter le montant restant
• examiner le paiement manuellement
• accepter le paiement selon une politique interne
• annuler ou rembourser la commande lorsque cela est approprié

Les sous-paiements ne doivent pas être automatiquement traités de la même manière que les paiements échoués. Ils doivent suivre un processus clair afin que les clients et les équipes de support sachent ce qui se passe ensuite.

7. Tester l’ensemble du flux de paiement

Avant de lancer l’intégration, testez le parcours client complet depuis la création du paiement jusqu’à la finalisation de la commande.

Vos tests doivent inclure :

• création réussie du paiement
• affichage correct de l’adresse et du QR code
• informations exactes sur le montant du paiement et le réseau
• mises à jour du statut de paiement
• finalisation réussie de la commande
• paiements expirés
• situations de sous-paiement
• notifications de paiement répétées
• mises à jour de paiement retardées

Vous devez également vérifier le fonctionnement de la page de paiement sur les appareils mobiles. De nombreux clients scanneront le QR code sur un autre appareil ou copieront directement l’adresse dans un portefeuille mobile.

Tester uniquement la requête API initiale ne suffit pas. L’ensemble du processus de commande, y compris les mises à jour de paiement et l’exécution, doit fonctionner de manière fiable avant que l’intégration ne soit proposée aux clients.

Considérations importantes pour l’intégration

Une expérience de paiement White Label fiable dépend de quelques détails pratiques.

Gestion de l’expiration

Lorsqu’un paiement expire, votre système doit cesser de le présenter comme actif. Le client doit pouvoir créer une nouvelle demande de paiement au lieu de continuer à utiliser les informations de paiement expirées.

Sélection correcte du réseau

Si une cryptomonnaie est prise en charge sur plusieurs réseaux, affichez clairement le réseau sélectionné.

Un client qui envoie des fonds via le mauvais réseau peut devoir contacter le support, et la récupération n’est pas toujours possible. Des instructions claires peuvent éviter bon nombre de ces erreurs.

Instructions de paiement claires

Les clients doivent comprendre immédiatement :

• quelle cryptomonnaie envoyer
• quel réseau utiliser
• quel montant envoyer
• où l’envoyer
• combien de temps le paiement reste valide
• ce qui se passe après le paiement

Une page de paiement claire réduit la confusion et crée une expérience de checkout plus fiable.

Flux d’intégration White Label

Le processus complet peut être résumé en sept étapes :

1. Votre système crée une commande interne.
2. Votre backend envoie une demande de paiement White Label à OxaPay.
3. OxaPay renvoie les détails du paiement.
4. Votre site web ou application affiche le paiement dans sa propre interface.
5. Le client envoie la cryptomonnaie demandée.
6. OxaPay surveille la transaction et envoie les mises à jour de paiement.
7. Votre système confirme le paiement et finalise la commande.

Conclusion

L’intégration de la passerelle de paiement crypto White Label d’OxaPay permet à une entreprise de contrôler son expérience de paiement sans construire l’ infrastructure blockchain sous-jacente elle-même.

OxaPay gère la génération des paiements, la surveillance des transactions et les mises à jour de paiement. Votre entreprise contrôle l’image de marque, l’interface client, la gestion des commandes et l’exécution finale.

L’idée est simple : votre entreprise maîtrise l’expérience client, tandis qu’OxaPay fournit l’infrastructure de paiement qui la sous-tend.

Avec une page de paiement claire, un suivi fiable des statuts et des tests appropriés, l’intégration White Label peut offrir aux clients une expérience de paiement crypto cohérente et entièrement connectée à votre site web ou application.