Retour aux guides INTÉGRATIONS

Intégration de Passerelle de Paiement : Guide Complet pour Développeurs et Entreprises

Intégrer une passerelle de paiement est l'une des décisions techniques les plus importantes qu'une entreprise e-commerce ou une équipe logicielle puisse prendre. La méthode choisie détermine votre périmètre PCI DSS, votre taux de conversion au checkout, votre capacité à gérer l'authentification 3D Secure et la rapidité avec laquelle vous pouvez prendre en charge de nouveaux moyens de paiement. Ce guide couvre chaque chemin d'intégration disponible, de la page hébergée sans code à une API REST complète serveur-à-serveur, et détaille les étapes exactes pour mettre en production avec RoxPay.

Intégration passerelle de paiement | RoxPay

Ce que l'intégration d'une passerelle de paiement signifie pour votre entreprise

Une intégration de passerelle de paiement est la connexion technique entre votre site web ou application et le réseau de traitement des paiements qui autorise, capture et règle les transactions par carte. Sans elle, vos clients ne peuvent pas payer. Avec une mauvaise intégration, vous perdez des revenus par des transactions échouées, des tunnels de paiement trop lourds et une mauvaise expérience mobile.

L'intégration impacte bien plus que les développeurs. Les dirigeants doivent comprendre que la méthode choisie détermine leur responsabilité sous PCI DSS, leur capacité à prendre en charge des moyens de paiement locaux et la rapidité d'activation de nouvelles fonctionnalités comme Apple Pay ou les virements open banking. Une page hébergée transfère toute la gestion des données de carte hors de vos serveurs et minimise votre charge de conformité. Une intégration API directe offre un contrôle maximal mais nécessite une certification PCI plus élevée.

Pourquoi la qualité de l'intégration compte pour la conversion : La friction au checkout est l'une des premières causes d'abandon de panier. Une passerelle nécessitant plusieurs redirections convertira moins bien qu'une expérience de paiement native et intégrée. Les intégrations REST API modernes permettent d'afficher les champs de saisie directement sur votre page sans que le client ne quitte votre site.

Pour les marchands dans des secteurs à risque élevé ayant besoin d'une passerelle de paiement à haut risque, la couche d'intégration est encore plus importante car les contrôles supplémentaires, l'application du 3D Secure et les filtres anti-fraude interagissent directement avec la façon dont le formulaire de paiement est conçu.

Méthodes d'intégration : Page hébergée, API et SDK

Il existe trois méthodes principales pour intégrer une passerelle de paiement, chacune avec des compromis différents entre rapidité d'implémentation, périmètre PCI DSS et flexibilité.

Page de paiement hébergée : L'option la plus simple. Vous redirigez le client depuis votre checkout vers une page hébergée par la passerelle. Le client saisit ses coordonnées bancaires sur le domaine de la passerelle, pas le vôtre. Cela élimine presque toutes les exigences PCI DSS de votre côté. L'inconvénient est la personnalisation limitée et l'expérience de quitter votre site en plein checkout.

Interface Drop-in intégrée (iFrame ou JS Elements) : Une voie intermédiaire pratique. La passerelle fournit un snippet JavaScript qui injecte des champs de saisie sécurisés directement dans votre page de checkout. Les champs s'affichent dans des iframes hébergées sur le domaine de la passerelle, donc les données de carte ne touchent jamais votre serveur. Périmètre PCI minimal (SAQ A). C'est l'approche recommandée pour la plupart des e-commerces. RoxPay supporte cela via son API REST et SDK frontend.

API serveur-à-serveur : Contrôle maximal. Votre frontend collecte les données de carte, votre serveur les envoie directement à l'API de la passerelle. Cela nécessite la conformité PCI DSS SAQ D avec des audits de sécurité rigoureux. Approprié uniquement pour les plateformes construisant des produits d'infrastructure de paiement.

Plugins et modules de plateforme : Pour les marchands utilisant Magento, PrestaShop ou WooCommerce, des modules pré-construits gèrent les détails d'intégration. La méthode sous-jacente est généralement une page hébergée ou une interface drop-in, donc le périmètre PCI reste minimal.

Étape par étape : Comment intégrer RoxPay via REST API

RoxPay fournit une API REST avec des corps de requête et réponse JSON. La documentation complète est disponible sur app.roxpay.eu/api/v4/docs. L'intégration suit un pattern standard d'intention de paiement familier à tout développeur ayant travaillé avec des API de passerelle modernes.

Étape 1 : Créez votre compte sandbox. Pour démarrer votre candidature RoxPay, accédez à la page d'onboarding. Les identifiants sandbox sont délivrés automatiquement à l'inscription, sans informations de paiement requises pour commencer les tests.

Étape 2 : Authentifiez-vous. Tous les appels API utilisent votre clé API dans l'en-tête Authorization. Ne jamais exposer votre clé API dans du JavaScript côté client ni la valider dans un système de contrôle de version.

Étape 3 : Créez une intention de paiement. POST sur l'endpoint d'intention de paiement avec le montant, la devise, les méthodes de paiement acceptées et une référence de commande unique. L'API retourne un ID d'intention de paiement et un secret client pour utilisation côté frontend.

Étape 4 : Montez l'interface drop-in. Passez le secret client à la bibliothèque RoxPay.js qui affiche les champs de saisie sur votre page. La bibliothèque gère le formatage des numéros de carte, la validation, les redirections 3D Secure et les boutons Apple Pay ou Google Pay.

Étape 5 : Gérez le résultat. En cas de paiement réussi, la bibliothèque déclenche un callback de succès. Votre frontend notifie votre backend, qui vérifie indépendamment le statut de paiement via webhook avant de traiter la commande. Ne vous fiez jamais uniquement à la confirmation frontend.

Étape 6 : Réconciliez via le tableau de bord. Toutes les transactions sont visibles dans votre tableau de bord marchand avec tous les détails sur le montant, les frais, le type de carte et le statut de règlement.

Webhooks, gestion des erreurs et tests en sandbox

Les webhooks sont la colonne vertébrale d'une intégration de paiement fiable. Ils permettent à RoxPay de notifier votre serveur des événements de paiement de manière asynchrone, sans dépendre du navigateur du client.

Configuration des webhooks : Enregistrez un endpoint HTTPS sur votre serveur dans le tableau de bord. RoxPay enverra un payload JSON signé à cet endpoint pour chaque événement significatif : payment.completed, payment.failed, payment.refunded, chargeback.created, et autres. Vérifiez la signature sur chaque webhook entrant en utilisant la clé secrète affichée dans votre tableau de bord.

Idempotence : Les webhooks peuvent être délivrés plus d'une fois. Votre endpoint doit traiter chaque événement de manière idempotente. Stockez l'ID d'événement et ignorez le traitement si vous l'avez déjà géré.

Gestion des erreurs dans l'API : RoxPay retourne des codes HTTP standard. 200 pour le succès, 400 pour les mauvaises requêtes, 401 pour les échecs d'authentification, 422 pour les erreurs de traitement comme un refus de carte.

Tests en sandbox : L'environnement sandbox reflète exactement la production. Utilisez les numéros de carte de test fournis pour simuler des transactions approuvées, des refus, des challenges 3DS, des fonds insuffisants, des cartes expirées et des réponses de carte volée.

Logique de réessai : Implémentez un backoff exponentiel sur votre consommateur webhook. RoxPay réessaie les webhooks non délivrés sur une période définie. Votre endpoint doit être idempotent avant de vous appuyer sur le comportement de réessai.

Mise en production : Checklist avant de traiter de vraies transactions

Passer du sandbox à la production nécessite de réaliser un ensemble d'étapes techniques, de sécurité et commerciales.

Checklist technique :
Remplacez les clés API sandbox par les clés de production et stockez-les dans des variables d'environnement, jamais dans le code source. Confirmez que votre endpoint webhook est en production, accessible via HTTPS avec un certificat valide. Testez la gestion de l'idempotence avec des identifiants de production. Confirmez que le 3D Secure est configuré selon les exigences de votre acquéreur. Validez que votre interface de checkout s'affiche correctement sur mobile.

Checklist PCI DSS :
Si vous utilisez l'interface drop-in, complétez et déposez un questionnaire d'auto-évaluation SAQ A. Confirmez que vous ne journalisez ni ne stockez aucune donnée de carte brute. Assurez-vous que votre configuration TLS respecte les standards actuels (TLS 1.2 minimum, TLS 1.3 recommandé).

Checklist commerciale :
Configurez votre descripteur de facturation dans le tableau de bord. C'est le texte qui apparaît sur le relevé bancaire du porteur de carte. Configurez votre IBAN de règlement. RoxPay règle sur tout compte bancaire SEPA en 24-48 heures. Activez les notifications email pour les transactions échouées et les contestations. Assurez-vous que votre contact support client est facilement accessible.

Questions fréquentes

Combien de temps prend l'intégration d'une passerelle de paiement ?

En utilisant l'approche drop-in UI avec l'API REST de RoxPay, un développeur expérimenté peut réaliser une intégration prête pour la production en un à deux jours. Une page hébergée avec redirection prend moins d'une journée. Une intégration API complète serveur-à-serveur avec un checkout personnalisé prend généralement une à deux semaines et nécessite également un niveau plus élevé de conformité PCI DSS.

Ai-je besoin d'être certifié PCI DSS pour intégrer une passerelle de paiement ?

Pas certifié au sens formel, mais vous devez être conforme. Si vous utilisez une page hébergée ou une interface drop-in (basée sur iFrame), votre charge de conformité est minimale et vous complétez un simple questionnaire d'auto-évaluation (SAQ A). Si vous gérez les données de carte brutes sur vos propres serveurs via une API serveur-à-serveur, vous avez besoin du SAQ D, qui implique un audit rigoureux.

Qu'est-ce qu'une intention de paiement et pourquoi est-elle utilisée ?

Une intention de paiement est un objet côté serveur qui représente l'intention d'un client de payer un montant spécifique. Elle suit l'état du paiement tout au long de l'autorisation, du challenge 3D Secure, de la capture et du règlement. L'utilisation d'un modèle d'intention de paiement empêche les doubles débits, permet un suivi webhook fiable et permet au paiement de survivre aux actualisations du navigateur.

Puis-je tester l'intégration sans compte marchand actif ?

Oui. RoxPay fournit un environnement sandbox gratuit accessible immédiatement après l'inscription. Le sandbox reflète exactement le comportement de production et inclut des cartes de test pour chaque scénario : approbations, refus, challenges 3DS, cartes expirées et fonds insuffisants.

Optimisez vos paiements dès aujourd'hui

RoxPay propose une API REST avec accès sandbox gratuit, documentation complète et règlement en 24-48h vers toute banque SEPA. Certifié PCI DSS Level 1, tarification IC++ à partir de 0,45%.

Activez gratuitement → Parler à un expert

✓ Aucun coût fixe mensuel · ✓ Activation en 24 heures · ✓ Support technique dédié