Sommaire | ||||
---|---|---|---|---|
|
...
Introduction
Objet du document
Ce document décrit la procédure d’intégration de la solution de paiement sécurisé en ligne Payline en mode API AJAX dans votre site commerçant.
Public visé
Ce document est destiné aux commerçants et intégrateurs qui souhaitent utiliser le mode d’intégration « API AJAX » la solution de paiement Payline.
Liste des documents de référence
Nos documents sont disponibles sur notre site internet www.payline.com ou sur simple demande auprès de notre service support : support@payline.com
Avertissement
Ce document est la propriété exclusive de Monext. Toute reproduction intégrale ou partielle, toute utilisation par des tiers, ou toute communication à des tiers, sans accord préalable écrit de Monext est illicite.
Monext®, marque communautaire et internationale propriété exclusive de Monext Ltd et/ou des sociétés du groupe.
Payline®, marque nationale et internationale propriété exclusive de Monext et/ou des sociétés du groupe.
Contacts
Vous avez besoin d’aide, de conseil ou vous souhaitez simplement nous poser une question ? Contactez l’Assistance Payline par : support@payline.com
Pour toute question liée à la mise en place de la solution Payline, vous pouvez joindre notre assistance technique par mail support@payline.com, du lundi au vendredi de 09h00 à 18h00.
Principe général
Présentation
L’interface AJAX présentée est une extension du mode direct. Le commerçant récupère les données carte sur la page récapitulative de commande hébergée sur ses serveurs. Ce mode permet l’exécution de la demande d’autorisation en mode synchrone ou asynchrone (via stockage temporaire du CVV), l’usage des fonctionnalités de portefeuille et permet de se libérer des obligations PCI-DSS.
L’interface AJAX
Deux modes d’intégration seront proposés :
- Le mode AJAX :
- Réservé aux navigateurs les plus récents, capables d’effectuer des appels AJAX « cross-domain » : IE8+, Chrome, Firefox et Safari ;
- L’intégration du type JSON-P n’est pas compatible avec PCI-DSS (passage du numéro de carte dans l’URL étant interdit) ;
- Intégration asynchrone dans les sites et dans les app-mobile (encore plus transparent pour l’acheteur) ;
- Pour les navigateurs non compatibles, le mode POST avec redirection temporaire :
- Le commerçant redirige brièvement l’acheteur sur Payline pour la tokenisation. Après traitement, Payline redirige de nouveau l’acheteur sur le site du commerçant ;
- Payline n’affiche aucune page Web, la redirection est donc transparente pour l’acheteur ;
- Ce mode d’intégration est compatible avec tous les navigateurs actuels.
Prérequis et précautions
Périmètre applicable
Le mode d’intégration avec l’API AJAX sur la solution de paiement Payline n’est pas adapté pour traiter les moyens de paiements avec redirection (Paypal, PaysafeCard, …) ou non soumis aux règles de PCI-DSS (vouchers prépayés, comptes eWallet, …).
...
Pour tous les autres moyens de paiement, le marchand peut utiliser l’API directe.
Sécurité
La collecte des données de paiement par le site marchand implique un risque plus élevé pour le commerçant. Ce mode d’intégration nécessite donc une application rigoureuse des standards de sécurité.
...
Le point 1 est particulièrement important : le marchand doit vérifier régulièrement si le script d’appel à la fonction getToken a été modifié. Si tel est le cas, il doit s’assurer que les préconisations restent valides.
Prérequis techniques
Pour les serveurs PHP les exemples de code fonctionnent :
...
Pour les serveurs J2E, afin de pouvoir accéder aux fonctions de chiffrement avec des clés supérieures à 128 bits, il faut installer le package Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy (http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html).
Description fonctionnelle
Cinématique d’un paiement simple
Voici les étapes principales d’un paiement avec cette nouvelle interface :
...
Figure 1 : Cinématique d’un paiement simple (sans 3DS)
Cinématique d’un paiement 3DSecure
Voici les étapes principales pour un paiement 3DSecure :
...
Figure 2 : Cinématique d’un paiement simple avec 3DSecure
Cinématique d’un paiement 3DSecure déclenché par le module anti-fraude
Voici les étapes principales pour un paiement 3DSecure déclenché par le module anti-fraude :
...
Figure 3 : Cinématique d’un paiement avec 3DSecure déclenché par le module LCLF
Cinématique d’enregistrement d’une carte dans un portefeuille
Dans ce scénario, aucun paiement n’est réalisé.
...
Figure 4 : Cinématique d’un enregistrement de carte dans le portefeuille Payline
Cinématique d’un second paiement par token
Dans cette cinématique, le commerçant a conservé au préalable le token de la carte (et la date d’expiration) dans sa base de données lors du premier paiement. La page de paiement affiche les cartes associées à ce compte acheteur.
Le commerçant a la possibilité de collecter le CVV auprès de son acheteur et le fournir lors de l’appel « doAuthorization » ou d’effectuer une transaction sans CVV.
...
- Le serveur commerçant
- recherche le token carte associé au client ;
- appelle WS Payline « doAuthorization » avec le token carte, avec ou sans CVV et un code action 120 ou 121.
- Le WS Payline « doAuthorization »
- appelle le tokenizer pour récupérer le numéro de carte réel ;
- envoie une autorisation à la banque du commerçant.
Implémentation
Modification de la gestion des clés commerçant
Les commerçants qui vont utiliser les paiements en mode AJAX doivent générer une clé d’accès à Payline avec le nouveau module de gestion. Ce nouveau module permet d’attribuer une référence de clé à chaque clé générée. Il est accessible au travers du centre d’administration dans le menu « Configuration ».
...
Figure 6 : nouvel écran de génération de clé d’accès
Fonction de création de token
Description
Ce service est développé sous la forme d’une Servlet nommée « getToken ». Il est à appeler au niveau de la page du commerçant pour obtenir le token de la carte de l’acheteur (requête AJAX ou requête POST+redirection).
Données en entrée
Nom du champ | Obligatoire | Format | Commentaire |
Données à générer par le commerçant | |||
accessKeyRef | O | AN(20) | Référence de la clé d’accès du commerçant |
data | O | AN | Données commerçant : Clé secrète : SHA-256 de la clé d’accès commerçant |
returnURL | F | AN | URL de retour sur le site du commerçant. |
Données de la carte saisies par l’acheteur | |||
cardNumber | O | N(19) | Numéro de la carte |
cardExpirationDate | F | MMYY | Date d’expiration |
cardCvx | F | N(4) | CVV |
...
Remarque : Le nombre de requêtes getToken est limité à 3 tentatives pour chaque référence commande. Si vous obtenez 3 erreurs lors d’une commande, il faudra re-générer une chaine chiffrée qui se base sur une nouvelle référence de commande.
Données en sortie
Le service retourne soit une liste de valeur encodées, soit un code erreur si la fonction ne s’est pas déroulée correctement.
...
Index | Valeur | Obligatoire | Format |
1 | Token associé au numéro de de carte Ex : 497910AztyqdEGdn123 | O | AN(19) |
2 | Date d’expiration de la carte (même donnée qu’en entrée) | F | MMYY |
3 | CVV virtuel, il devra être restitué dans la demande d’autorisation sans être modifié Ex. : v456 | F | AN(5) |
4 | Référence commande identique à celle passée en entrée. Pour éviter un éventuel rejeu, le commerçant doit contrôler que cette référence est bien celle attendue. Si tel n’est pas le cas, il doit refuser la transaction et envoyer une annulation à Payline | O | AN(50) |
5 | Type de carte Ex. : VISA | O | AN |
6 | Indicateur « isCVD » (carte virtuelle) | O | Y ou N |
7 | Code pays de la carte Ex. : FR | F | AN(2) |
8 | Code produit de la carte Ex. : L (pour Electron) | F | AN(3) |
9 | Code de la banque émettrice de la carte Ex : 30003 | F | AN(11) |
Codes d’erreur
Code | Message court | Message long |
09101 | Transaction refused | Accès non autorisé |
09102 | Transaction refused | Compte commerçant bloqué ou désactivé |
02703 | Transaction refused | Action non autorisée |
02303 | Transaction refused | Numéro de contrat invalide |
02623 | Transaction refused | Nombre d’essai maximal atteint |
02624 | Transaction refused | Carte expirée |
02625 | Transaction refused | Format du numéro de carte incorrect |
02626 | Transaction refused | Format de la date d’expiration incorrect ou date non fournie |
02627 | Transaction refused | Format du CVV incorrect ou CVV non fourni |
02628 | Transaction refused | Format de l’URL de retour incorrect |
02631 | Transaction refused | Délai d’attente expiré |
API webservice
Les webservices Payline ont évolué de façon à être compatible avec le paiement en mode Ajax.
...
Production : https://secure.payline.com/webpayment/getToken
Exemples d’implémentation
Trois étapes sont nécessaires :
Ancre | ||||
---|---|---|---|---|
|
Préparation de la page de collecte des données carte
Avant de présenter la page à ses acheteurs, le commerçant doit préparer les éléments qui serviront à envoyer la demande de token à Payline :
...
À noter que la chaîne de caractères chiffrée (obtenue à l’étape 5) doit être encodée en base64url (cf. https://fr.wikipedia.org/wiki/Base64#base64url).
Code serveur PHP
Préparer un hash de la clé d’accès :
...
Avec :
merchantId : identifiant Payline du commerçant
orderRef : référence unique de la commande en cours
contractNumber : numéro de contrat Payline sur lequel va porter le paiement.
Code serveur J2E
Préparer un hash de la clé d’accès :
...
Bloc de code | ||||
---|---|---|---|---|
| ||||
byte[] msgUtf8 = (merchantId+orderRef+ContractNumber).getBytes("UTF-8"); SecretKeySpec secretKeySpec = new SecretKeySpec(accessKeyBytes, "AES"); Cipher cipher = Cipher.getInstance("AES"); cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec); byte[] ciphered = cipher.doFinal(msgUtf8); String crypted = Base64.encodeBase64URLSafeString(ciphered); |
Avec :
merchantId : identifiant Payline du commerçant ;
orderRef : référence unique de la commande en cours ;
contractNumber : numéro de contrat Payline sur lequel va porter le paiement.
Ancre | ||||
---|---|---|---|---|
|
Page de paiement
La page de paiement doit implémenter un fonctionnement qui garantit que le numéro de carte saisit par l’acheteur ne sera jamais stocké (ni par le navigateur de l’acheteur, ni par le serveur web du commerçant).
...
Exemple utilisable dans un formulaire du type :
Bloc de code | ||||
---|---|---|---|---|
| ||||
<form id="paymentForm" action="#" method="post"> <input type="hidden" name="data" id="data" size='255' value="<?php echo $crypted ?>" /> <input type="hidden" name="accessKeyRef" id="accessKeyRef" value="<?php echo $accessKeyRef ?>" /> <label for="">Numéro de carte</label> <input type="text" name="cardNumber" id="cardNumber"/> <label for="">Date d'expiration</label> <input type="text" name="cardExpirationDate" id="cardExpirationDate"/> <label for="">Cryptogramme</label> <input type="text" name="cardCvx" id="cardCvx"/> <br/> <input type="submit" class="btn btn-primary" value="Payer" /> </form> |
Avec :
crypted : données chiffrées préparées à l’étape précédente
accessKeyRef : référence de la clé d’accès commerçant
Ancre | ||||
---|---|---|---|---|
|
Traitement de la réponse
La réponse contient des données qu’il faut déchiffrer et décompresser, le tout étant codé en base64url.
...
Pour plus d’information sur l’API webservice, vous pouvez consulter la documentation associée.
Serveur PHP
Déchiffrer les données reçues :
...
Bloc de code | ||||
---|---|---|---|---|
| ||||
$paylineDataResponse=explode(';', $uncompressedData); $cardToken = $paylineDataResponse[0]; $cardExpirationDate = $paylineDataResponse[1]; $cardVirtualCVV = $paylineDataResponse[2]; $orderReference = $paylineDataResponse[3]; … |
Serveur J2E
Déchiffrer les données reçues :
...