Introduction
WL Sips est une solution de paiement de commerce électronique multicanale sécurisée conforme à la norme PCI DSS. Elle vous permet d'accepter et de gérer des transactions de paiement en prenant en compte les règles métiers liées à votre activité. (paiement à la livraison, paiement différé, paiement récurrent, en plusieurs fois, ...).
Afin d'être en conformité avec la DSP2, il est nécessaire de basculer de la solution Subscription 1.0 vers la nouvelle solution Abonnement 2.0.
L'objectif du présent document est de vous expliquer la migration de Subscription 1.0 vers la solution Abonnement 2.0.
Sujets non couverts dans le présent document :
- Ce document ne présente que la migration vers Sips Paypage 2.0 POST, connecteur recommandé sur Sips Paypage 2.0. Si vous souhaitez utiliser le connecteur Sips Paypage 2.0 JSON, merci de vous référer au guide dédié.
- Ce document ne présente que la migration vers Sips Office 2.0 JSON, connecteur recommandé sur Sips Office 2.0. Si vous souhaitez utiliser le connecteur Sips Office 2.0 SOAP, merci de vous référer au guide dédié.
À qui s'adresse ce document
Ce document est à destination des commerçants disposant de l'offre WL Sips 1.0. Il a pour but de faciliter la migration vers WL Sips 2.0.
Pour connaître tous les détails de l'utilisation des pages de paiement Sips Paypage 2.0, merci de vous référer au document Sips Paypage 2.0 POST.
Pour connaître tous les détails de l'utilisation de Sips Office 2.0, merci de vous référer au document Sips Office 2.0 JSON.
Pour connaître tous les détails de l'utilisation de Sips Office Batch 2.0, merci de vous référer aux documents Sips Office Batch XML ou Sips Office Batch CSV.
La réglementation
Dans le cadre de la réglementation DSP2, un chaînage des transactions doit être réalisé afin de garantir la mise en place d'une authentification pour une série d'opérations de paiement. On distingue en effet la transaction initiale (Customer Initiated Transaction, ou CIT), émise lors de l'enregistrement de l'abonné, et le paiement ultérieur récurrent (Merchant Initiated Transaction, ou MIT) qui doit être chaîné à la transaction initiale (CIT).
Consultez à ce sujet notre documentation sur le chaînage.
Principe
Ce qui ne change pas avec WL Sips 2.0 | Ce qui change avec WL Sips 2.0 | |
---|---|---|
Données et formats | La base des abonnés est conservée. | Nouvelle URL. |
Pages d'enregistrement des abonnés | Les pages d'enregistrement des abonnés sont conservées. | |
Identification de la transaction | Possibilité d'utiliser une nouvelle référence de transaction de 35 caractères alpha-numériques. | |
Configuration | Vous n'installez plus aucun fichier chez vous, quelle que soit l'interface WL Sips que vous choisissez. | |
Sécurité | Le certificat WL Sips est remplacé par une clé secrète. | |
Transfert de fichier | Le transfert de fichier est conservé. | |
Moyens de paiement | Les moyens de paiement utilisés restent identiques. | La gestion du choix de moyen de paiement est déportée chez WL Sips 2.0. |
Juridique | Contrat VADS chez l'acquéreur. |
Ce que vous devez faire
- Décider du connecteur Sips Paypage 2.0 à utiliser (POST, JSON).
- Décider du connecteur Sips Office 2.0 à utiliser (JSON, SOAP).
- Décider du format de fichier de Sips Office Batch (XML ou CSV).
- Décider de rester avec la gestion du transactionId ou passer au transactionReference.
- Mettre en place votre requête de paiement en sécurisant votre nouvelle clé secrète.
- Revoir la structure de vos fichiers requêtes pour qu'ils soient compatibles avec Sips Office Batch 2.0.
- Revoir le traitement de vos fichiers réponses au format Sips Office Batch 2.0.
- Utiliser l'environnement de recette client pour tester les applications Sips Paypage 2.0, Sips Office 2.0 ou Sips Office Batch 2.0 avec un identifiant de connexion mis à disposition par WL Sips.
- Mettre en oeuvre les données de production (url, clé secrète et merchant_id).
- Démonter l'API 1.0 Subscription (certificat, fichiers de configuration, etc.).
- Conserver en interne la date d'expiration de la carte bancaire de l'abonné afin de lui demander d'enregistrer sa nouvelle carte lorsque son ancienne carte expire.
Tableau de correspondance
Vous utilisez actuellement une seule API WL Sips 1.0 pour gérer vos abonnements. En 2.0, nous vous proposons d'utiliser plusieurs connecteurs avec leur spécificités et fonctionnalités. Pour vous guider, vous trouverez ci-dessous un tableau de correspondance:
Fonction | WL Sips 1.0 | WL Sips 2.0 |
---|---|---|
Collecte des coordonnées de paiement | Subscription | Sips Paypage 2.0 |
Paiements récurrents mode batch | Subscription | Sips Office Batch 2.0 |
Paiements récurrents mode M2M | PayId | Sips Office 2.0 |
Migration Subscription vers Sips Paypage 2.0 + Sips Office Batch 2.0

Migration Subscription vers Sips Paypage 2.0 + Sips Office 2.0

Choix du mode transactionId ou transactionReference
Par défaut, les connecteurs 2.0 utilisent un transactionReference pour identifier une transaction vers le serveur de paiement. Cet identifiant est unique pour toute la durée de l’inscription du commerçant sur WL Sips, il n’est pas réutilisable pour une autre transaction. Si vous souhaitez rester en mode transactionId / transactionDate, vous devez en faire la demande à WL Sips lors de l’inscription de votre identifiant marchand à l’offre WL Sips 2.0 afin que la configuration de votre identifiant marchand soit conforme à l’attendu.
Les champs à utiliser dans la requête de paiement seront donc :
TransactionReference | AN35 | Identifiant unique de la transaction |
ou
s10TransactionReference. s10TransactionId | N6 | TransactionReference est le moyen par défaut d’identifier une transaction. s10TransactionReference.s10TransactionId est une alternative pour identifier une transaction, en restant compatible avec WL Sips 1.0. |
Migration du traitement de la prise d'abonnement
La collecte des coordonnées de paiement se fait sur Sips Paypage 2.0.
Choix du connecteur Sips Paypage 2.0
Ce document ne présente que le connecteur POST (formulaire envoyé au serveur WL Sips en mode POST).
Si vous souhaitez que le premier appel au serveur de paiement soit réalisé en mode « machine à machine » avec la technologie JSON, merci de vous référer au document Sips Paypage POST pour la mise en place des requêtes de paiement dans ce mode.
Comment passer de l'API Subscription 1.0 au connecteur Sips Paypage POST 2.0
Ce tutoriel se base sur l'utilisation de l'API Subscription 1.0 en langage PHP telle qu'elle est packagée initialement. Toutefois ce tutoriel est transposable aux autres langages de programmation.
Les fichiers du répertoire param
Avec l'API Subscription 1.0, le répertoire par défaut param contient les fichiers parmcom et pathfile de paramètres par défaut de la boutique. Ces fichiers ne sont maintenant plus utilisés.
Le nouveau formulaire utilisé sur Sips Paypage 2.0 doit embarquer la récupération des informations concernant les paramètres par défaut du commerçant et permettant de se connecter à Sips Paypage 2.0 pour effectuer la requête de paiement.
Le fichier pathfile, contenant les chemins de l'installation de Subscription 1.0 sur le serveur du commerçant n'est plus utilisé, aucune de ces informations n'étant utile à Sips Paypage 2.0. Ce fichier sera donc à supprimer lorsque la migration sera terminée.
La plupart des données du fichier parmcom sont enregistrées dans la configuration du commerçant lors de son inscription à WL Sips 2.0. Cependant, certaines données peuvent être forcées dans la requête de paiement si elles restent compatibles avec les données connues lors de l'inscription du comerçant. Aussi, certaines autres données (par exemple, la devise du montant) restent obligatoires dans la requête.
Donnée parmcom | Champ de la requête Sips Paypage 2.0 | Obligatoire/Facultatif |
---|---|---|
sub_automatic_response_url | automaticResponseURL | Facultatif |
sub_normal_return_url | normalReturnURL | Obligatoire |
card_list | paymentMeanBrandList | Facultatif |
currency_code | currencyCode | Obligatoire |
language | customerLanguage | Facultatif |
templatefile | templateName | Facultatif |
Données de base du formulaire web
Le nouveau formulaire doit embarquer la récupération des informations concernant le commerçant et permettant de fabriquer la requête de paiement, par exemple :
//Initialisation des données commerçant
$merchantid=<valeur du merchandId Sips>;
$secretKey=<clé secrète du commerçant>;
$keyVersion=<version de la clé secrète du commerçant>;
$tref='tref01';
Contrairement à l’API Subscription 1.0 où les données étaient envoyées à l’exécutable recordabo.exe contenu dans le répertoire bin, il faudra maintenant calculer un champ nommé Data contenant les données de la requête et un champ Seal contenant l’empreinte du message à envoyer.
Calcul du champ Data
Le champ Data est en réalité le nom donné au message complet de la requête (= concaténation de tous les champs de la requête).
L'étape suivante consiste donc à calculer le champ Data avec les données de la requête (ici avec un montant de 1 euro) :
$Data='amount=100|currencyCode=978|merchantid='.$merchantid.'|automaticResponseUrl=http://www.mon
_url_marchand.com/call_autoresponse.php|normalReturnUrl=http://www.mon_url_marchand.com/call_response.php
|transactionReference='.$tref.'|keyVersion='.$keyversion.'|customerLanguage=fr;
Calcul du champ SEAL
Les paramètres de la transaction (requête de paiement) sont envoyés au travers du navigateur de l’internaute. Théoriquement, il est possible à un hacker de modifier les paramètres durant la transmission des données vers le serveur de paiement.
Il est par conséquent nécessaire d’ajouter de la sécurité pour assurer l’intégrité des paramètres transmis de la transaction. La solution WL Sips répond à ce besoin par l’échange de signatures, nommées empreintes du message.
Un contrôle réussi des signatures implique deux choses :
- L’intégrité des messages requête et réponse, pas d’altération durant l’échange,
- L’authentification de l’émetteur et du receveur car ils partagent la même clé secrète.
Le calcul de l’empreinte du message grâce au hash du champ Data par la clé secrète du commerçant :
$Seal=hash('sha256', $Data.$secretkey);
Formulaire en mode POST
Et enfin, envoi du formulaire en mode POST avec les données (exemple avec l’URL de l’environnement de recette) :
echo '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1250">
<title>REDIRECTION TO PAYMENT PAGE</title>
</head>
<body>
<form method="post" action="https://payment-webinit.test.sips-services.com/paymentInit">';
echo '<input type="text" name="Data" size="300" value="'.$Data.'"><br>';
echo '<input type="text" name="InterfaceVersion" size="300" value="HP_2.7"><br>';
echo '<input type="text" name="Seal" size="300" value="'.$Seal.'"><br>';
echo '<br><input type="submit" value="Connection to https://payment-webinit.test.sips-services.com/paymentInit 2.0">';
echo '</form></body></html>';
Récupération en réponse du paiement
Les réponses automatiques et manuelles seront à adapter par rapport aux versions présentées sur Subscription 1.0.
Les fichiers de traitement des réponses donnés en exemple dans le répertoire example se nomment call_responseabo.php et call_autoresponseabo.php.
Contrairement à Subscription 1.0 où les données étaient envoyées à l’exécutable responseabo.exe contenu dans le répertoire bin, il faudra maintenant récupérer le champ nommé Data contenant les données de la réponse et vérifier le champ Seal contenant l’empreinte du message reçu.
Récupération des données de base de la réponse
Le nouveau formulaire doit embarquer la récupération des informations de la réponse lui permettant d’interpréter le résultat de la requête de paiement, par exemple :
// Récupération des données de la réponse
$Data=htmlspecialchars($_POST[“Data”]);
$Seal=htmlspecialchars($_POST[“Seal”]);
//Séparation de tous les champs
$tableau = explode ("|", $Data);
Afin d’assurer un suivi sur la transaction et sur les données du client, il est important de sauvegarder ces données :
Données | Notes |
---|---|
maskedPan | Vous permettra de personnaliser les affichages du client. |
panExpiryDate | Vous permettra d’avertir le client pour l’ajout d’une nouvelle carte. |
s10TransactionId | Seulement si vous êtes en mode TransactionId/TransactionDate. Vous permettra de sauvegarder la transaction initiale à reprendre lors de l’opération walletOrder. |
s10TransactionDate | Seulement si vous êtes en mode TransactionId/TransactionDate. Vous permettra de sauvegarder la date de la transaction initiale. |
Calcul du champ SEAL
Ensuite calcul de l’empreinte du message grâce au hash du champ Data par la clé secrète du commerçant :
$SealCalc=hash('sha256', $Data.$secretkey);
Il faudra ensuite vérifier que le Seal correspond au Seal reçu dans la requête.
Suppression des références à Subscription 1.0
Lors de l’installation de Subscription 1.0, l’arborescence suivante est créée sur le serveur :
Les fichiers de Sips Paypage 2.0 n’ayant plus rien à voir avec cette arborescence, vous pouvez complètement supprimer les fichiers présents.
Migration des paiements récurrents
Mode Batch : passage du batch Subscription vers Sips Office Batch 2.0
Nommage des fichiers
Une modification au niveau du nommage des fichiers est nécessaire :
- Le fichier requête doit être transmis dans une archive au format ZIP. L’archive doit se nommer OFBREQxx.ZIP. Le fichier doit respecter le nommage [ Sips Office Batch ].[Alias].[Date].[Heure].[Format fichier].
- Le fichier réponse est transmis dans une archive au format ZIP. Le nom de cette archive est OFBREPxx.[Jour].[Mois].[Année].ZIP. Le nom du fichier contenu dans cette archive a pour formalisme OFFUBZ.OFFBAREP.[Alias].[Date]-[Heure].[Format du fichier].
Structure du fichier
- Vous allez devoir adapter l’écriture de votre fichier. Vous avez la possibilité de choisir entre deux formats : XML ou CSV.
- Contrairement au fichier batch SUB qui était constitué de trois parties ; entête, détail, fin, le fichier Sips Office Batch 2.0 est constitué de quatre parties successives ; FILE TYPE, HEADER, BODY, END.
- Les champs FORMAT et VERSION (qui n’existent pas sur le batch Subscription 1.0) sont obligatoires sur Sips Office Batch 2.0. En effet, sur Sips Office Batch 2.0, ces champs dépendent du type de service appelé :
Format | Version | Description du service |
---|---|---|
office | Doit avoir la valeur 10 | Acceptation des transactions et des opérations de caisse. |
Veuillez vous référez aux documents Sips Office Batch XML et Sips Office Batch CSV pour plus d'information.
- Exemple de type de fichier sur Batch SUB 1.0 (champs séparés par
des « : » ou des espaces au format SUB 1.0)
03fr023101122334455000001A96ZQ701 SOBSIMS336499270000000001000978 ::customer.email@worldline.com159 00106556e55fe2f863b831052020122329 MASTERCARD:5133.4404202200
- Exemple de type de fichier au format CSV sur Sips Office Batch 2.0 (champs séparés par des « ; » au format CSV
SOB2.0)
FILE;request;office;v10 HEADER;023101122334455; 2020-08-17+0200;111:19:16+0100;DUPLICATE ;1023101122334455;SOBSIMS62958901 ;1000;;;978;2;AUTHOR_CAPTURE; customer.email@worldline.com ;1000000000000000011;123.6.53.68;;; INTERNET;159;;;;;;;;;;;;;;;;440012;20200817;;
- Exemple de type de fichier au format XML sur Sips Office Batch 2.0
<file type="request" format="office" version="v10"> <header> <remitterId>023101122334455</remitterId> <date>2020-08-17+02:00</date> <time>11:19:10+01:00</time> <sequence>1</sequence> </header> <body> <duplicate recordSequence="1"> <merchantId>023101122334455</merchantId> <transactionReference>SOBSIMS33649927</transactionReference> <amount>599</amount> <currencyCode>978</currencyCode> <captureDay>2</captureDay> <captureMode>AUTHOR_CAPTURE</captureMode> <customerEmail>customer.email@worldline.com</customerEmail> <customerId>1000000000000000011</customerId> <customerIpAddress>123.6.53.68</customerIpAddress> <orderChannel>INTERNET</orderChannel> <orderId>159</orderId> <s10TransactionReference> <s10TransactionId>440012</s10TransactionId> <s10TransactionIdDate>20200817</s10TransactionIdDate> <s10TransactionReference> </duplicate> </body> <end nbRecord="1"/> </file>
Code retour de traitement
Sur le batch SUB, 3 types de réponses sont retournées : la réponse globale, la réponse par abonné et la réponse par acquéreur. Sur Sips Office Batch 2.0 il existe les réponses lors de la vérification du fichier et les réponses causées par une opération.
Pour les réponses lors de la vérification de fichier, il y a plusieurs niveaux de codes réponses lors du traitement d'un fichier par Sips Office Batch. Ces codes réponses sont retournés dans le champ processingResponseCode sur Sips Office Batch 2.0. Plusieurs vérifications globales sont effectuées avant que le fichier ne soit traité. Si l'une de ces vérifications échoue, le fichier est entièrement refusé (processingResponseCode n'est égal ni à 00 ni à 01). Le fichier de réponses retourné contient le code de résultat global du traitement dans le champ processingResponseCode présent dans l'en-tête du fichier.
Récapitulatif des valeurs possibles du champ processingResponseCode (WL Sips 2.0) avec une comparaison de la réponse globale (batch SUB) :
Code | Signification processingResponseCode (WL Sips2.0) | Code | Signification du code de la réponse globale (Batch SUB 1.0) |
---|---|---|---|
00 | Fichier traité correctement : Le fichier contient la liste des opérations. | 00 | Fichier traité correctement : (voir code par abonné pour détail) |
01 | Fichier traité correctement : Une opération a été associée à un commerçant qui n'est pas lié à l'identifiant de remettant. Le champ officeBatchResponseCode sera valorisé à 80 par l'opération. | N/A | |
02 | Fichier déjà traité : Le numéro de séquence du fichier est inférieur à ce qu'il devrait être. Le numéro correct est envoyé dans le message qui décrit l'erreur. | 02 | Fichier déjà traité. |
03 | Rupture de séquence dans le numéro de séquence du fichier. Le numéro de séquence du fichier est supérieur à ce qu'il devrait être. Le numéro correct est envoyé dans le message qui décrit l'erreur. | 03 | Rupture de séquence dans le numéro de séquence du fichier. |
04 | Problème technique. Problème interne | 99 | Problème technique sur le serveur d'abonnement. |
05 | Fichier trop grand | N/A | |
06 | Le nombre d'opérations dépasse la quantité maximale autorisée. Le nombre maximal d'opérations a été atteint. | N/A | |
07 | Le nombre d'opérations compté est différent du nombre indiqué dans le champ nbRecord. | N/A | |
08 | Opération en double | N/A | |
09 | Enregistrement invalide | 12 | Transaction invalide (format correcte, contenu incorrect) |
10 | Format de fichier invalide : Le format du fichier est invalide (la description de l'erreur sera retournée dans la balise « error details »). | 01 | Format incorrect. |
11 | Remettant invalide : Le remettant déclaré dans l'en-tête est invalide. | 14 | Abonné inconnu |
N/A | 04 | Fichier non cohérent (compteur faux, entête ou fin invalide ou manquant) | |
Autres codes | Fichier invalide : Ces codes concernent les versions plus anciennes de Sips Office Batch. | N/A |
Pour les erreurs causées par une opération, chaque opération étant indépendante, elle a son propre code de réponse stocké dans le champ officeBatchResponseCode. Ce code indique le champ qui est à l’origine du problème.
Pour connaître ces codes, vous pouvez vous référer à la documentation Sips Office Batch XML – Analyser les erreurs par opération
Ou Sips Office Batch CSV – Analyser les erreurs par opération
La réponse acquéreur au niveau du batch SUB n’est pas reportée dans Sips Office Batch 2.0.
Opération walletOrder
La fonction walletOrder
va vous
permettre d’effectuer des paiements en utilisant les informations
contenues dans le wallet de vos clients. Vous pouvez vous référez à la
documentation Sips Office Batch XML - Fonction walletOrder ou Sips Office Batch CSV - Fonction walletOrder.
Mode M2M : passage du composant PayId vers Sips Office 2.0
Choix du connecteur Sips Office 2.0
Ce document ne présente que le connecteur JSON (requête envoyée au serveur WL Sips en mode JSON).
Si vous souhaitez que les appels au serveur de paiement soient réalisés en mode « machine à machine » avec la technologie SOAP, merci de vous référer au document Sips Office SOAP pour la mise en place des requêtes dans ce mode.
Les fichiers du répertoire param
Le composant PayId contient un répertoire param qui contient le fichier pathfile de paramètres par défaut de la boutique et le certificat de la boutique. Ces fichiers ne sont maintenant plus utilisés.
Le fichier pathfile, contenant les chemins de l’installation de Sips Office sur le serveur du commerçant n’est plus utilisé, aucune de ces informations n’étant utile à Sips Office 2.0. Ce fichier sera donc à supprimer lorsque la migration sera terminée.
Les échanges avec Sips Office 2.0
Contrairement au composant PayId qui est installé en local sur votre serveur, les échanges avec Sips Office 2.0 se font par requête JSON sur l’URL du service concerné.
Il faudra maintenant calculer un champ nommé Seal contenant l’empreinte du message à envoyer.
Calcul du champ SEAL
Les paramètres de la requête (requête de paiement ou opération de gestion de caisse, de wallet) sont envoyés de machine à machine. Théoriquement, il est possible à un hacker de modifier les paramètres durant la transmission des données vers le serveur de paiement.
Il est par conséquent nécessaire d’ajouter de la sécurité pour assurer l’intégrité des paramètres transmis de la transaction. La solution WL Sips répond à ce besoin par l’échange de signatures, nommées empreintes du message.
Un contrôle réussi des signatures implique deux choses :
- L’intégrité des messages requête et réponse, pas d’altération durant l’échange,
- L’authentification de l’émetteur et du receveur car ils partagent la même clé secrète.
Le calcul de l’empreinte du message est réalisé comme suite :
- Concaténation des valeurs des champs dans l’ordre alphabétique, sans prise en compte du champ keyVersion et du champ sealAlgorithm.
- Encodage UTF-8 des données du résultat précédent.
- HMAC avec cryptage SHA256 des données obtenues avec la clé secrète.
Le calcul de l’empreinte du message, peut être résumé ainsi :
$Seal=hash_hmac('sha256', $Data, $secretkey);
Opération walletOrder
L’opération walletOrder
va vous
permettre d’effectuer des paiements en utilisant un des moyens de paiement
contenus dans le Wallet de vos clients. Vous pouvez vous référer à la
documentation Sips Office JSON - Fonction walletOrder ou Sips Office SOAP - Fonction walletOrder
Test sur l'environnement de recette
Lorsque toutes ces étapes de migration ont été effectuées, vous pouvez passer à la phase de test sur l'environnement de recette, en utilisant les données de test disponibles sur notre site de Documentation en ligne.
Au préalable vous devez faire une demande de création de boutique en environnement de test incluant tous les connecteurs déployés sur votre site ainsi que les livrables permettant la personnalisation des pages (pour Sips Paypage).
D'autre part, dans le cadre de l'utilisation du connecteur Sips Office Batch, des paramètres spécifiques doivent être mis en place sur votre boutique de recette afin que l'échange des fichiers entre notre serveur et votre compte FTP puisse s'effectuer.
Enfin vous devrez nous indiquer quels services vous souhaitez utiliser: moyens de paiements, opérations de caisse).
Annexes
Annexe 1 : Arborescence documentaire
Dans cette annexe vous trouverez un tableau récapitulatif des documents de référence pour accompagner votre migration:
Besoin | Document de référence |
---|---|
Connecteurs | Sips Paypage POST |
Sips Office JSON | |
Sips Office Batch CSV | |
Chaînage MIT/CIT | Chaînage MIT/CIT |
3-D Secure | 3-D Secure |
Personnalisation des pages | Migration de la personnalisation des pages de paiement (Paypage) |
Journaux | Correspondance des journaux 1.0 2.0 |
Champs | Correspondance des données 1.0 2.0 |
Dictionnaire des données | Dictionnaire des données |
Documentation en ligne | Documentation en ligne |
Sips Office Extranet | Sips Office Extranet |
Merchant Extranet | Merchant Extranet |
Sips Download | Sips Download |
CustomPages | CustomPages |