Intégration e-commerce

Intégration e-commerce
Version 0.6
14 février 2014
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
14/02/2014
Version du document
0.6
Version de l‘application (à usage interne)
2.10
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
Description
status
Code réponse http (200 si la requête réussit).
amount_min
Montant minimum autorisé par transaction (en euros).
amount_max
Montant maximum autorisé par transaction (en euros).
currencies
Tableau des devises autorisées pour votre compte, au format
ISO 4217 (par exemple ‘ EUR ‘ pour l’euro).
url
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’).
yourPrivateKey
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’).
payplugPublicKey
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
La monnaie utilisée (seul l’euro est acceptée, indiquer ‘EUR’).
ipn_url
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 »).
return_url
(optionnel) URL sur laquelle PayPlug redirige le client en cas de succès.
email
(optionnel) Adresse email du client.
firstname
(optionnel) Prénom du client.
lastname
(optionnel) Nom du client.
order
(optionnel) Identifiant de commande dans votre base de données
customer
(optionnel) Identifiant du client dans votre base de données
custom_datas
(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
Description
id_transaction
Identifiant de transaction PayPlug. Nous vous conseillons de
l’enregistrer et l’associer dans votre site à la commande concernée.
status
Le statut de la transaction (0 = paiement, 4 = remboursement)
customer
Les données du champ ‘customer’ fourni lors du paiement.
order
Les données du champ ‘order’ fourni lors du paiement.
custom_datas
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 Questions 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