WL SIPS DOCS

Release 22.6

aller directement au contenu

Rechercher par mots clés

Migration Payment Subscription 1.0 vers Abonnement 2.0 via duplication

Pour rechercher dans la page utiliser Ctrl+F sur votre clavier

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 d'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é.

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.

Sips Paypage 2.0 permet de ne plus stocker de fichiers spécifiques à l’appel des pages de paiement sur votre serveur .

Aussi, le choix du moyen de paiement peut être réalisé sur votre serveur commerçant (en spécifiant lors de l’appel le moyen de paiement utilisé) ou côté serveur de paiement Sips Paypage 2.0.

Enfin, avec Sips Paypage 2.0 POST, seul un formulaire en mode POST sera envoyé vers les serveurs Sips Paypage 2.0 pour réaliser la cinématique de paiement. La redirection est automatiquement réalisée par le serveur de paiement vers la page de saisie des informations des moyens de paiement.

  • Possibilité d'utiliser une nouvelle référence de transaction de 35 caratères Alpha-Numériques.
  • Nouvelle URL.
  • La gestion du choix de moyen de paiement est déportée chez WL Sips.
  • Le certificat WL Sips est remplacé pour une clé secrète.
  • Le commerçant n'installe plus aucun fichier chez lui, quelle que soit l'interface WL Sips 2.0 qu'il choisit.
  • 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 sa requête de paiement en sécurisant sa nouvelle clé secrète.
  • Revoir la structure de ses fichiers requêtes pour qu'ils soient complatibles avec Sips Office Batch 2.0.
  • Revoir le traitement de ses 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.
  • Faire une demande d'accès en production.
  • Supprimer les références à Subscription 1.0, au composant PayId 1.0 et/ou au Batch SUB sur son site (certificat, fichiers paramètres, fichiers exécutables).
  • 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.

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.

La collecte des coordonnées de paiement se fait sur 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.

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.

Attention: tous les exemples de code sont présentés en langage PHP et sont à personnaliser pour une utilisation réelle en production. Ils ne sont pas à reproduire tel que et ne sont là que pour présenter rapidement comment se connecter à Sips Paypage 2.0.

Avec l'API Subscription 1.0, le répertoire par défaut param contient les fichiers parcom 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 parcom 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 parcom 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

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 WL 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.

Puis calcul du 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;

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 votre clé secrète :

$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 VERS PAGE DE PAIEMENT</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="Connexion a WL Sips 2.0">';   
echo '</form></body></html>';

Merci de vous référer au document Sips Paypage JSON afin d’obtenir de l’aide sur la mise en place d’un appel en JSON.

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.

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 Duplicate.
s10TransactionDate Seulement si vous êtes en mode TransactionId/TransactionDate. Vous permettra de sauvegarder la date de la transaction initiale.

Ensuite calcul de l’empreinte du message grâce au hash du champ Data par votre clé secrète :

$SealCalc=hash('sha256', $Data.$secretkey);

Il faudra ensuite vérifier que le Seal correspond au Seal reçu dans la requête.

Lors de l’installation de Subscription 1.0, l’arborescence suivante est créée sur le serveur :


Liste des dossiers et fichiers de subscription 1.0

Un dossier subscription contenant les dossiers bin, example, logo et param et les fichiers uninstall.exe et Version.txt.

Les fichiers de Sips Paypage 2.0 n’ayant plus rien à voir avec cette arborescence, vous pouvez complètement supprimer les fichiers et dossiers présents.

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].
  • 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 :
  • Exemple de type de fichier sur Batch SUB 1.0 (champs séparés par des « : » ou des espaces au format SUB 1.0)
    03fr​023101122334455​000001A96ZQ701
    SOBSIMS33649927​0000000001000978
    ::customer.email@​worldline.com159
    00106556e55fe2f863​b831052020122329
    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;1​11: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>
    

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.

Pour continuer à faire de l’abonnement, vous allez devoir utiliser la méthode Duplicate qui vous permettra de créer une nouvelle transaction à partir des données d’une transaction initiale, réalisée sur Sips Paypage 2.0. Vous pouvez vous référez à la documentation Sips Office Batch XML - Fonction Duplicate

Ou Sips Office Batch CSV - Fonction Duplicate

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.

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.

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.

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);

Le composant PayId va être remplacé par l’opération Duplicate. Elle vous permettra de créer une nouvelle transaction à partir des données d’une transaction initiale, réalisée sur Sips Paypage 2.0. Vous pouvez vous référez à la documentation Sips Office JSON - Fonction Duplicate

Ou Sips Office SOAP - Fonction Duplicate

Au préalable, il faut faire la demande de création de boutique de tests puis d’installation des livrables permettant la personnalisation des pages de paiement afin qu'ils soient installés sur l’environnement de recette Sips Paypage 2.0.

Merci de vous référer au document Custompages d'aide à la migration de la personnalisation des pages de paiement.

Au préalable, vous devez faire la demande de création d’une boutique de test. Lors de cette demande, il faut préciser que vous souhaitez tester la solution Sips Office Batch 2.0. En effet, un paramétrage de la boutique de recette est nécessaire afin que l’échange de fichiers entre notre serveur et votre compte sFTP puisse s’effectuer.


description des api et connecteurs utilisés avant et après migration

Avant la migration, vous utilisez l'API subscription 1.0 pour le premier paiement et l'API Batch SUB 1.0 pour les échéances suivantes. Après la migration, vous utilisez Sips Paypage pour le premier paiement puis la fonction duplicate de Sips Office Batch pour les échéances suivantes.

Au préalable, il faut faire la demande de création d’une boutique de test. Lors de cette demande, il faut préciser quels services à tester sont souhaités (paiement, gestion de caisse, wallet). Vous pouvez ensuite tester toutes les opérations mises à disposition. Merci de vous référer au document pour la mise en place des requêtes dans ce mode.


description des api et connecteurs utilisés avant et après migration

Avant la migration, vous utilisez l'API subscription 1.0 pour le premier paiement et le composant PayId 1.0 pour les échéances suivantes. Après la migration, vous utilisez Sips Paypage pour le premier paiement puis la fonction duplicate de Sips Office pour les échéances suivantes.

Ce site utilise des traceurs pour améliorer votre expérience de navigation, effectuer des analyses et des recherches sur votre utilisation du site web de documentation WL Sips.
En fermant ce bandeau vous refusez notre utilisation des traceurs sur votre appareil.

Paramètres