Intégration e-commerce Version 0.5 13 décembre 2013 1
Table des matières 1 Introduction... 3 Fonctionnement général... 3 La sécurité... 3 2 Paramètres de votre compte... 4 3 Création d un paiement... 5 Le paramètre <base_url>... 5 Le paramètre <data>... 5 Le paramètre <signature>... 6 Avertissement sur l URL de retour... 6 4 Instant Payment Notification (IPN)... 7 5 Question fréquentes... 8 Comment tester mon intégration?... 8 La fonction getallheaders n existe pas, que dois-je faire?... 8 Comment appeler l url d autoconfig depuis PHP?... 8 Historique Date de création 09/08/2013 Date de mise à jour 13/12/2013 Version du document 0.5 Version de l application (à usage interne) 2.8 2
1 Introduction Ce document décrit l intégration du système de paiement PayPlug à tout site de vente en ligne par l intermédiaire de l URL de paiement. Ce mode de fonctionnement s adresse aux développeurs qui souhaitent utiliser PayPlug sur un site e-commerce ou qui souhaitent développer un module de paiement pour une solution existante (Magento, Wordpress, WooCommerce, Prestashop,...). Fonctionnement général Le paiement PayPlug se déroule en 3 étapes : 1. Vous créez une URL de paiement personnalisée vers PayPlug, qui comprend notamment le montant et l URL de retour post-paiement 2. Vous dirigez votre client vers cette url qui est une page de paiement sécurisée (exemple : https://www.payplug.fr/exemple) 3. Une fois le paiement terminé, PayPlug renvoie le visiteur vers l URL de retour que vous avez spécifié en créant le paiement En parallèle, PayPlug envoie une notification IPN (Instant Payment Notification) à votre serveur, contenant les données de la transaction, pour vous indiquer que le paiement a été effectué. La sécurité PayPlug permet de sécuriser les paiements avec la bibliothèque Open SSL qui repose sur un cryptage par clé publique/privée RSA. Ce dispositif garantit aux e-commerçants qui n ont pas de site sécurisé par SSL un niveau de sécurité équivalent à SSL mais sans la complexité de mise en place d une connexion HTTPS. Tous les échanges de données entre le serveur de votre site et celui de PayPlug sont donc signés afin de certifier que les données n ont pas été modifiées. Ce mécanisme intervient dans deux situations : 1. Signature des messages écrits par le site e-commerce à destination de PayPlug 2. Vérification des notifications de paiement provenant de PayPlug (IPN) 3
2 Paramètres de votre compte Votre application a besoin d un certain nombre de paramètres de configuration avant de pouvoir générer sa première URL de paiement. Ces paramètres sont liés à votre compte PayPlug, si vous n avez pas encore de compte, vous pouvez vous inscrire en une minute sur https://www.payplug.fr/inscription. Les paramètres de configuration sont disponibles via l URL de configuration : https://www.payplug.fr/portal/ecommerce/autoconfig (une authentification avec votre identifiant et mot de passe PayPlug est nécessaire). Cette page de configuration contient un objet au format JSON qui comprend les champs suivants : Nom status amount_min amount_max currencies url yourprivatekey payplugpublickey Description Code réponse http (200 si la requête réussit). Montant minimum autorisé par transaction (en euros). Montant maximum autorisé par transaction (en euros). Tableau des devises autorisées pour votre compte, au format ISO 4217 (par exemple EUR pour l euro). L URL où vous devez diriger l utilisateur au moment du paiement, complétée des champs data et signature (voir Le paramètre <base_url> dans la section Créer un paiement ). Votre clé privée servant à signer les données de transaction que vous envoyez à PayPlug. Sans cette signature, le service refuse la demande de transaction (voir Créer un paiement ). La clé qui vous permet de vérifier l origine des données envoyées par PayPlug en IPN (voir Notifications ). Si cette signature n est pas bonne, vous ne devez pas prendre en compte le retour fourni par PayPlug car il pourrait avoir été modifié par un intermédiaire. Nous conseillons d accéder une fois à cette URL de configuration depuis votre application, et de sauvegarder les paramètres dans un fichier, ou dans la base de données de votre application par exemple. Remarque : la clé privée yourprivatekey et la clé publique payplugpublickey doivent être au format PEM (il s agit de la représentation en base 64 d une clé privée RSA). Vous pouvez trouvez des exemples du format des clés aux adresses suivantes : - Clé privée : https://gist.github.com/splanquart/7827287 - Clé publique : https://gist.github.com/splanquart/7827462 4
3 Création d un paiement Pour accepter un paiement, vous devez diriger le visiteur du site vers une URL de la forme : <base_url>?data=<data>&sign=<signature>. Exemple de code en PHP : $url = $base_url. "?data=".$data. "&sign=".$signature; header("location: $url"); exit(); Le paramètre <base_url> Il s agit de l URL associée à votre compte, récupérée sur la page de configuration. Le paramètre <data> Le paramètre data contient les données de transaction que vous devez envoyer à PayPlug. Ces données doivent être encodées en base64 puis sous forme d URL. Exemple de code en PHP : $params = array('amount'=>$amount, ); $url_params = http_build_query($params); $data = urlencode(base64_encode($url_params)); Voici les champs attendus : Nom Description amount Montant de la transaction en centimes (par exemple 4207 pour 42,07 euros). Votre application doit vérifier que ce montant est compris entre les montants minimum et maximum (voir Paramètres de configuration ). currency ipn_url return_url email firstname lastname order customer custom_datas La monnaie utilisée (seul l euro est acceptée, indiquer EUR ). Instant Payment Notification : URL de votre site que le serveur PayPlug appellera dès que la transaction est validée ou remboursée. Veillez à ce que cette URL soit accessible depuis Internet. Généralement, ce n est pas le cas pour un poste de développement («en local»). (optionnel) URL sur laquelle PayPlug redirige le client en cas de succès. (optionnel) Adresse email du client. (optionnel) Prénom du client. (optionnel) Nom du client. (optionnel) Identifiant de commande dans votre base de données (optionnel) Identifiant du client dans votre base de données (optionnel) Données supplémentaires de votre base de données 5
Si vous laissez l un des champs email, firstname, lastname vide, ils seront demandés au client. Les champs order, customer et custom_datas vous sont transmis lors d un appel sur ipn_url, et vous permettent de valider une commande. Ils permettent de faciliter le rapprochement entre vos données et celles disponibles sur la plateforme PayPlug. Le paramètre <signature> Le paramètre signature est une signature de type SHA1 + RSA calculé sur la valeur du champ data (non encodé en base64 c est à dire la variable $url_params dans notre exemple ci-dessous). Le calcul de cette signature doit se faire avec la clé privée que vous avez sauvegardée lors de la récupération des paramètres de configuration. La signature doit être encodée en base64 puis encodée sous forme d URL. Exemple de code en PHP : /* $pvkey = la valeur de yourprivatekey que vous avez sauvegardé en récupérant les paramètres de configuration */ $privatekey = openssl_pkey_get_private($pvkey); openssl_sign($url_params, $signature, $privatekey, OPENSSL_ALGO_SHA1); $signature = urlencode(base64_encode($signature)); Avertissement sur l URL de retour Quand le client est dirigé sur l URL de retour return_url, vous devriez déjà avoir reçu la notification de paiement (IPN) depuis notre serveur (voir la section suivante). Si ce n est pas encore le cas, nous vous conseillons de passer la commande à un état En cours, afin d empêcher l utilisateur de payer ce panier à nouveau, tout en ne considérant pas la commande comme payée. Vous devriez recevoir l IPN sous quelques minutes. 6
4 Instant Payment Notification (IPN) Lorsqu une transaction est validée ou remboursée, PayPlug envoie une requête HTTP de type POST à l URL fournie dans le champ ipn_url lors du paiement. Attention, l URL que vous fournissez doit être accessible depuis internet, pour que vous soyez en mesure de recevoir la requête POST de PayPlug. Cela signifie que vous ne pouvez pas utiliser une URL uniquement accessible en local, ou protégée par un firewall. Les données se trouvent dans le corps de la requête, qui est signée par PayPlug. La signature se trouve dans le champ PayPlug-Signature de l entête de la requête, et est calculée de la même manière que pour la demande de paiement via SHA1 + RSA. Vous devez vérifier la signature avant de prendre en compte les données de l IPN. Pour cela, utilisez la clé publique payplugpublickey de la page de configuration. Voici les paramètres fournis par PayPlug lors de cet appel : Nom id_transaction status customer order custom_datas Description Identifiant de transaction PayPlug. Nous vous conseillons de l enregistrer et l associer dans votre site à la commande concernée. Le statut de la transaction (0 = paiement, 4 = remboursement) Les données du champ customer fourni lors du paiement. Les données du champ order fourni lors du paiement. Les données du champ custom_datas fourni lors du paiement. Exemple de vérification de la signature en PHP : $headers = getallheaders(); /* Pour plus de sécurité, mettre les clés en majuscule et de récupérer la signature en utilisant la clé en majuscule : */ $headers = array_change_key_case($headers, CASE_UPPER); $signature = base64_decode($headers[ PAYPLUG-SIGNATURE ]); /* Les données sont envoyées dans le corps de la requête POST au format JSON (type MIME = application/json). Exemple : {"status": 0, "customer": "2", "id_transaction": 4121, "custom_datas": "29", "order": "42"} */ $body = file_get_contents('php://input'); $data = json_decode($body, true); /* $pbkey = la clé publique de PayPlug que vous avez sauvegardé depuis la page des paramètres de configuration */ $publickey = openssl_pkey_get_public($pbkey); $issignaturevalid = openssl_verify($body, $signature, $publickey, OPENSSL_ALGO_SHA1); if($issignaturevalid){ /* Prendre en compte l IPN */} 7
5 Question fréquentes Comment tester mon intégration? Concernant le test de l'api, nous n'avons pas d environnement de test ou «sandbox». En revanche, nous vous invitons à effectuer de véritables transactions puis à les rembourser par la suite : nous remboursons aussi les commissions. Cela vous permettra de tester votre intégration en conditions réelles sans aucun frais. La fonction getallheaders n existe pas, que dois-je faire? La fonction PHP getallheaders() est un alias de la fonction apache_request_headers(), et fonctionne donc seulement si vous utilisez Apache comme serveur (elle fonctionne aussi avec FastCGI depuis PHP 5.4). Dans les autres cas, vous pouvez trouver un exemple de code à l adresse suivante : https://gist.github.com/splanquart/7826749. Comment appeler l url d autoconfig depuis PHP? Vous pouvez utiliser la fonction «curl_exec» de PHP. Un exemple est disponible à l adresse suivante : https://gist.github.com/splanquart/7827949. 8