Intégration e-commerce. Version 0.4

Transcription

1 Intégration e-commerce Version octobre

2 Table des matières 1 Introduction... 3 Fonctionnement général... 3 La sécurité Paramètres de votre compte Créer un paiement... 5 Le paramètre <base_url>... 5 Le paramètre <data>... 5 Le paramètre <signature> Notifications... 7 Instant Payment Notification (IPN)... 7 Avertissement sur l URL de retour... 8 Historique Date de création 09 Août 2013 Date de mise à jour 16 octobre 2013 Version du document 0.4 Version de l'application (à usage interne) 2.1 2

3 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 : 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 vous envoie une notification IPN (Instant Payment Notification) avec les données de la transaction. La sécurité Sur internet, la sécurité des paiements passe par l utilisation d une connexion sécurisée par SSL (https). PayPlug s adresse principalement à des petits commerçants qui dans bien des cas n ont pas de site sécurisé avec https. Dans ce contexte, PayPlug utilise un niveau de sécurité similaire à 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 signés, afin de certifier que les données n'ont pas été modifiées. Ce mécanisme utilise un cryptage par clé publique/privée RSA avec la bibliothèque OpenSSL dans deux situations : 1. Signature des messages écrits par le site e-commerce à destination de PayPlug 2. Vérification des messages provenant de PayPlug (IPN) 3

4 2 Paramètres de votre compte Avant de commencer votre développement, vous devez prendre connaissance des paramètres de votre compte, accessibles via la page de configuration : Vous aurez besoin de votre identifiant et mot de passe PayPlug pour y accéder ; si vous n avez pas de compte PayPlug, vous pouvez vous inscrire en une minute sur Cette page de configuration contient un objet au format JSON qui comprend les champs suivants : Nom du champ status amount_min amount_max currencies url yourprivatekey PayPlugPublicKey Description 200 si 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 L URL où vous devez diriger l utilisateur au moment du paiement, complétée des champs data et signature (voir 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. La clé qui vous permet de vérifier l origine des données envoyées par PayPlug en IPN. 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. 4

5 3 Créer 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 = $url_payment."?data=".$data."&sign=".$signature; header("location: $url"); exit(); Le paramètre <base_url> Il s agit de votre URL unique associée au compte PayPlug du site web. Vous la trouverez dans le champ url accessible sur votre 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 du champ amount currency ipn_url return_url Description Montant de la transaction en centimes La monnaie utilisée (actuellement seul l euro est supporté, la valeur attendue est EUR ) Instant Payment Notification : URL de votre site que le serveur PayPlug appellera dès que la transaction est validée ou annulée URL sur laquelle PayPlug redirige le client en cas de succès. Si ce champ est vide, le visiteur est dirigé sur la page post-paiement PayPlug. Adresse du client. Si vous laissez l un des champs , firstname, lastname vide, ces informations seront demandées au client. 5

6 firstname lastname order customer Prénom du client. Si vous laissez l un des champs , firstname, lastname vide, ces informations seront demandées au client. Nom du client. Si vous laissez l un des champs , firstname, lastname vide, ces informations seront demandées au client. (optionnel) Identifiant de commande dans votre base de données (optionnel) Identifiant du client dans votre base de données custom_datas (optionnel) Données supplémentaires de votre base de données 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). Le calcul de cette signature doit se faire avec la clé privée que vous trouverez dans le champ «yourprivatekey» de l autoconfig. La signature doit être encodée,en base64 puis sous forme d URL. Exemple de code en PHP : $url_params = ; $privatekey = openssl_pkey_get_private( ); openssl_sign($url_params, $signature, $privatekey, OPENSSL_ALGO_SHA1); $signature = urlencode(base64_encode($signature)); 6

7 4 Notifications Instant Payment Notification (IPN) Lorsque la transaction est validée ou refusée, PayPlug envoie une requête de type POST à l URL fournie dans l URL de paiement (dans le champ ipn_url). C'est cet appel qui valide le paiement dans votre site. 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 envoyées par l IPN. Pour cela, vous devez utiliser la clé publique de PayPlug fournie via le champ «payplugpublickey» dans l autoconfig. Voici les paramètres fournis par PayPlug lors de cet appel : Champ Description Exemple id_transaction Identifiant de transaction PayPlug. Nous vous conseillons d enregistrer cet id et de l associer à la commande concernée status customer order custom_datas Le statut de la transaction (0 : transaction payée, 1 : transaction remboursée) Les données du champ customer fourni lors de la demande de paiement Les données du champ order fournit lors de la demande de paiement Les données du champ custom_datas fourni lors de la demande de paiement Exemple de vérification de la signature en PHP : $headers = getallheaders(); /* Pour plus de sécurité nous conseillons de mettre les clés de ce tableau 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 envoyées sont contenues dans le corps de la requite 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); $publickey = openssl_pkey_get_public( ); 7

8 $isvalid = openssl_verify($body, $signature, $publickey, OPENSSL_ALGO_SHA1); if(isvalid){ } 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. Si ce n est pas encore le cas, nous vous conseillons de passer la commande à un état En cours de traitement, 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. 8