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, paiement en plusieurs fois , …).

L’objectif du présent document est d’expliquer la mise en œuvre de la solution Sips Walletpage SOAP jusqu’au démarrage en production.

A qui s’adresse ce document

Ce document est destiné aux commerçants qui souhaitent souscrire à l’offre WL Sips et utiliser un connecteur fondé sur les échanges SOAP entre leur site Web et les serveurs WL Sips pour permettre à leurs clients de gérer leur wallet oneClick ou leur wallet abonné.

C’est un guide d’implémentation qui s’adresse à l’équipe technique du commerçant.

Pour avoir une vue d’ensemble de la solution WL Sips , nous vous conseillons de consulter les documents suivants :

  • Présentation fonctionnelle,
  • Guide de Configuration des fonctionnalités,
  • Guide du paiement OneClick,
  • Guide du paiement par abonnement.

Prérequis

Une connaissance élémentaire des standards relatifs aux langages de programmation Web pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour développer la connexion à Sips Walletpage SOAP .

Note: toutes les portions de code de ce document sont fournies à titre d’exemple, il convient de les adapter à votre site Web afin qu’elles soient pleinement exploitables.

Gestion de la clé secrète

Lors de votre inscription, Worldline met à disposition sur Sips Download (voir l'annexe "Télécharger la clé secrète"), une clé secrète qui permet de sécuriser les échanges entre votre site et le serveur WL Sips .

Vous êtes responsable de sa conservation et devez prendre toutes les mesures pour :

  • en restreindre l'accès ;
  • la sauvegarder de manière chiffrée ;
  • ne jamais la copier sur un disque non sécurisé ;
  • ne jamais l'envoyer (e-mail, courrier) de manière non sécurisée.

La compromission de la clé secrète (et son utilisation par un tiers malveillant) perturberait le fonctionnement normal de votre boutique, et pourrait notamment générer des transactions et des opérations de caisse injustifiées (des remboursements par exemple).

IMPORTANT: en cas de compromission d’une clé secrète, vous êtes tenu d’en demander au plus vite la révocation puis le renouvellement via Sips Download (voir l'annexe « Révocation et demande de renouvellement de la clé secrète » du guide de démarrage rapide).

C’est la même clé secrète qui est utilisée sur les différents connecteurs Sips Paypage , Sips Office , Sips In-App et Sips Walletpage .

IMPORTANT: une clé secrète est associée à une version. Après avoir obtenu une nouvelle clé secrète, vous devez impérativement modifier votre requête et indiquer la nouvelle version dans le champ keyVersion , sans quoi vous obtiendrez un code réponse 34 (suspicion de fraude).

Comprendre la gestion des wallets client avec Sips Walletpage SOAP

Le principe général d’un processus de gestion de wallet est le suivant :

1. Lorsque le client initialise l’étape de gestion de wallet, une requête doit être envoyée au connecteur Sips Walletpage SOAP dont Worldline fournit l’URL. La requête est alors vérifiée, et chiffrée si elle est valable (elle est nommée RedirectionData dans le système). La requête est envoyée au moyen d’un formulaire en mode POST via HTTPS. Toute autre solution capable d’envoyer une requête de cette nature fonctionne également.

2. Le site du commerçant redirige l’application appelante vers l’interface de gestion de wallet avec la requête chiffrée. Celle-ci est déchiffrée et Sips Walletpage permet au client d’effectuer différentes opérations sur son wallet. Pour que le client puisse retourner sur votre site, une réponse est créée et envoyée à l’URL de réponse fournie dans le flux n°1.

Il y a deux notifications de réponses indépendantes :

3. Le serveur de gestion de wallet envoie la réponse manuelle via HTTP(S) POST vers l’URL de réponse manuelle, laquelle est fournie dans la requête de gestion de wallet lorsque le client clique sur « Retour à la boutique » sur la page de gestion de wallet. C’est pourquoi l’URL de réponse normale est également la page vers laquelle le client est redirigé à l’issue des opérations de gestion de wallet. Comme il n’y a aucune garantie que le client clique sur ce lien, la réception de la réponse manuelle n’est pas garantie non plus.

4. Les réponses automatiques sont envoyées indépendamment des réponses manuelles. Elles utilisent également les requêtes HTTP(S) POST envoyées par les serveurs de gestion de wallet mais, cette fois-ci moyennant l’URL de la réponse automatique précisée dans la requête de gestion de wallet. Vous recevez la réponse lorsque le client cliquera sur le bouton « retour à la boutique » ou si la session de gestion du wallet aura expiré.

Démarrer avec Sips Walletpage SOAP en 5 étapes

Étape 1 : souscrire au service

Si votre boutique n’a pas encore été inscrite, vous devez remplir le formulaire d’inscription (en demandant le service abonnement ou le service oneClick) envoyé par Worldline et le retourner à ce dernier.

Si votre boutique est déjà inscrite sur WL Sips , vous devez demander au contact technique d’activer le service abonnement ou le service oneClick.

Note: si votre base wallet est partagée entre plusieurs boutiques, vous devez l’indiquer dans le formulaire d’inscription ou le dire à l’assistance technique.

Si ce n’est pas précisé, WL Sips définit une base wallet dédiée à votre boutique.

Étape 2 : gérer le wallet de vos clients

La requête de gestion de wallet consiste en un appel vers un service Web SOAP. En réponse, ce service Web vous fournira l’URL vers laquelle rediriger l'Internaute ainsi que les champs redirectionData et redirectionVersion . Vous devez effectuer cette redirection via un formulaire HTML au moyen de la méthode POST.

Générer la requête de gestion de wallet

Tous les champs nécessaires pour la gestion de wallet (voir les détails dans le chapitre « Renseigner les champs de la requête ») doivent être fournis.

La donnée InterfaceVersion doit être fixée à WMR_WS_ 2.6 .

Syntaxe de la requête

La requête est construite conformément au format SOAP.

Exemple d’une requête de gestion de wallet :
      <soapenv:Body>
      <urn:walletManagementInit>
         <urn:input>
            <urn:responseKeyVersion>1</urn:responseKeyVersion>
            <urn:merchantWalletId>9865578</urn:merchantWalletId>
            <urn:requestDateTime> 2014-12-19T14:06:06.273+01:00</urn:requestDateTime>
            <urn:interfaceVersion>WMR_WS_2.5</urn:interfaceVersion>
            <urn:merchantId>011223744550001</urn:merchantId>
         <urn:normalReturnUrl>http://www.normalreturnurl.com</urn:normalReturnUrl>
         </urn:input>
      </urn:walletManagementInit>
   </soapenv:Body>
    

Sécuriser la requête

La requête contient les paramètres de la transaction et est envoyée par le navigateur Web du client. Il est théoriquement possible pour un pirate d’intercepter la demande et de la modifier avant l’envoi au serveur de paiement.

De ce fait, il est nécessaire de renforcer la sécurité pour assurer l’intégrité des paramètres de la transaction envoyée. WL Sips répond à ce besoin par un échange de signatures qui permet de vérifier :

  • l’intégrité des messages requête et réponse ;
  • l’authentification de l’émetteur et du destinataire car ils se partagent la même clé secrète ;
IMPORTANT: si votre clé secrète est compromise, ou si vous supposez que c’est le cas, vous devez impérativement demander son renouvellement en vous connectant à Sips Download .

Comment sécuriser la requête

La sécurisation de la requête est effectuée en calculant la valeur « hashée » conformément aux paramètres de la transaction (donnée Data ). Ensuite, la clé secrète y est ajoutée. Toutes les chaînes de caractères sont converties en UTF-8 avant le « hashage ».

L’algorithme de « hashage » génère un résultat irréversible. Lorsqu’un tel message est reçu, le destinataire doit recalculer la valeur « hashée » pour la comparer à celle reçue. Toute différence indique que les données échangées ont été falsifiées ou que le destinataire et l’émetteur ne partagent pas la même clé secrète.

Le résultat doit être envoyé sous forme hexadécimale dans la donnée nommée Seal .

Calcul de la donnée Seal

Algorithme HMAC-SHA

La valeur de la donnée Seal est calculée comme suit :

  • concaténation des valeurs des champs de données dans l’ordre alphabétique (respectant le code de caractères ASCII) des noms des champs, sauf pour les champs keyVersion et sealAlgorithm . Donnant la donnée data , mentionnée dans les exemples ci-dessous.
    • exemple : un champ nommé authorResponseMessage est à positionner avant un champ nommé authorisationId ;
  • obtention de l’encodage UTF-8 des données du résultat précédent ;
  • HMAC avec chiffrement SHA256 des octets obtenus avec la clé secrète.

Cette procédure peut être résumée comme suit :

      HMAC-SHA256( UTF-8(sortedDataValues), UTF-8(secretKey))
    
Note: par défaut, le sceau est calculé avec l'algorithme HMAC-SHA-256. Pour qu’un sceau soit calculé avec l'algorithme SHA-256, les paramètres d'entrée de la requête doivent contenir le champ sealAlgorithm avec la valeur suivante : “SHA-256”.
Exemples de code Hmac Sha256
  • Exemple d’encodage Hmac Sha256 en Php 5
            <?php
    
    …
    
    // Seal computation thanks to hash sorted data hash with merchant key
    
    $data_to_send= utf8_encode($data)
    
    $seal=hash_hmac('sha256', $data_to_send, $secretKey);
    
    …
    …
    
    ?> 
          

    data_to_send et secretKey doivent utiliser un jeu de caractères UTF-8. Référez-vous à la fonction utf8_encode pour la conversion de caractères ISO-8859-1 en UTF-8.

  • Exemple d’encodage Hmac Sha256 en Java
            import java.security.InvalidKeyException;
    import java.security.NoSuchAlgorithmException;
    
    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    
    public class ExampleHMACSHA256 {
    
    /**
     * table to convert a nibble to a hex char.
     */
    static final char[] hexChar = {
       '0' , '1' , '2' , '3' ,
       '4' , '5' , '6' , '7' ,
       '8' , '9' , 'a' , 'b' ,
       'c' , 'd' , 'e' , 'f'};
    
    /**
     * Fast convert a byte array to a hex string
     * with possible leading zero.
     * @param b array of bytes to convert to string
     * @return hex representation, two chars per byte.
     */
    public static String encodeHexString ( byte[] b )
       {
       StringBuffer sb = new StringBuffer( b.length * 2 );
       for ( int i=0; i<b.length; i++ )
          {
          // look up high nibble char
          sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );
    
          // look up low nibble char
          sb.append( hexChar [b[i] & 0x0f] );
          }
       return sb.toString();
       }
    
    /**
     * Computes the seal
     * @param Data the parameters to cipher
     * @param secretKey the secret key to append to the parameters 
     * @return hex representation of the seal, two chars per byte.
     */
    public static String computeSeal(String data, String secretKey) throws Exception
    {
      Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
      SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      hmacSHA256.init(keySpec);
    
      return encodeHexString(hmacSHA256.doFinal(data.getBytes()));
    }
    
    /**
     * @param args
     */
    public static void main(String[] args) {
    try {
    System.out.println (computeSeal("parameters", "key"));
    } catch (Exception e) {
    e.printStackTrace();
    }
    }
    
    }
          
  • Exemple d’encodage Hmac Sha256 en .net

    (Exemple effectué à l’aide d’un simple formulaire nommé « Form1 » contenant deux champs texte pour saisir data et txtSecretKey , ainsi qu’un autre champ pour afficher  lblHEX ).

            using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Text;
    using System.Windows.Forms;
    using System.Security.Cryptography;
    
    namespace ExampleDotNET
    {
        public partial class Form1 : Form
        {
            public Form1()
            {
                InitializeComponent();
            }
    
            private void cmdGO_Click(object sender, EventArgs e)
            {
                String sChaine = data.Text;
                UTF8Encoding utf8 = new UTF8Encoding();
                Byte[] encodedBytes = utf8.GetBytes(sChaine);
            
                byte[] shaResult;
                
                HMAC hmac = new HMAC.Create("HMACSHA256");
                var key = "YourSecretKey";
                hmac.Key = utf8.GetBytes(key); 
                hmac.Initialize();
    
                shaResult = hmac.ComputeHash(encodedBytes);
    
                lblHEX.Text = ByteArrayToHEX(shaResult);
            }
    
            private string ByteArrayToHEX(byte[] ba)
            {
                StringBuilder hex = new StringBuilder(ba.Length * 2);
                foreach (byte b in ba)
                    hex.AppendFormat("{0:x2}", b);
                return hex.ToString();
            }
    
        }
    }
          
Validation du calcul de seal

Une fois votre calcul de seal mis en place, voici un exemple de requête vous permettant de vérifier que vous retrouvez bien le bon seal :

            <urn:walletManagementInit>
         <urn:input>
            <urn:urn:automaticResponseUrl>https://automatic-response-url.fr/</urn:urn:automaticResponseUrl>
            <urn:normalReturnUrl>https://normal-return-url/</urn:normalReturnUrl>
            <urn:customerContact>
                <urn:email>customer@email.com</urn:email>
            </urn:customerContact>
            <urn:interfaceVersion>WMR_WS_2.4</urn:interfaceVersion>
            <urn:keyVersion>1</urn:keyVersion>
            <urn:merchantId>011223344550000</urn:merchantId>
            <urn:merchantWalletId>wallet01</urn:merchantWalletId>
            <urn:requestDateTime>2018-08-08T16:31:22.589+02:00</urn:requestDateTime>
            <urn:seal>5aad3874f828bc427cd58833164bdfcfd8bcdf7b0921addc9ef82e6f82b027ee</urn:seal>
         </urn:input>
      </urn:walletManagementInit>
    

Pour la requête ci-dessus, la chaîne concaténée que vous devez calculer est la suivante :

      https://automatic-response-url.fr/customer@email.comWMR_WS_2.4011223344550000wallet01https://normal-return-url/2018-08-08T16:31:22.589+02:00
    

Avec un algorithme de hachage HMAC-SHA-256 et une clé secrète valant :

      secret123
    

Le seal attendu est :

      5aad3874f828bc427cd58833164bdfcfd8bcdf7b0921addc9ef82e6f82b027ee
    

Exemple de requête de gestion du wallet

Ci-dessous, voici un exemple de requête au format XML SOAP 1.1 :

      <soapenv:Body>
      <urn:walletManagementInit>
         <urn:input>
            <urn:responseKeyVersion>1</urn:responseKeyVersion>
            <urn:merchantWalletId>9865578</urn:merchantWalletId>
            <urn:requestDateTime> 2014-12-19T14:06:06.273+01:00</urn:requestDateTime>
            <urn:interfaceVersion>WMR_WS_2.5</urn:interfaceVersion>
            <urn:merchantId>011223744550001</urn:merchantId>
         <urn:normalReturnUrl>http://www.normalreturnurl.com</urn:normalReturnUrl>
            <urn:responseEncoding>base64</urn:responseEncoding>
         </urn:input>
      </urn:walletManagementInit >
   </soapenv:Body>
    

Exemple de formulaire de redirection vers Sips Walletpage SOAP

En réponse à cette requête, vous devez recevoir une réponse (également en XML SOAP 1.1 ) contenant les champs suivants :

Nom du champ Description
redirectionData Token de la requête à fournir lors de la redirection vers les pages de de gestion de wallet.
redirectionStatusCode Liste des codes réponse possibles.
redirectionStatusMessage Court message donnant le statut de l’initialisation.
redirectionUrl Url des pages de gestion de wallet WL Sips vers lesquelles il faut rediriger le client.
redirectionVersion Version de la redirection.
seal Seal de sortie.
reponseEncoding Type d’encodage utilisé dans les réponses.

Si l’initialisation de la gestion du wallet s’est correctement déroulée, le champ redirectionStatusCode doit être valorisé à « 00 ». Les champs redirectionData, redirectionVersion et redirectionUrl seront également valorisés pour permettre la redirection vers les pages de gestion du wallet WL Sips .

Pour rediriger le client vers les pages de gestion de wallet, vous devez implémenter un formulaire de type POST envoyant les deux champs suivants : redirectionData et redirectionVersion . Le formulaire POST devra rediriger le client vers l’URL fourni dans le champ redirectionUrl .

Ci-dessous, voici un exemple de formulaire qui devra être soumis de façon automatique :
      <form method="post" action=”value of redirectionURL”>
<input type="hidden" name="redirectionVersion" value=”value of redirectionVersion”>
<input type="hidden" name="redirectionData" value=”value of redirectionData”>
</form>
    

Traiter les erreurs lors de l’initialisation de la gestion de wallet

Tous les champs reçus par Sips Walletpage SOAP à travers le connecteur font l’objet d’une vérification individuelle. Le tableau ci-dessous présente la liste des codes d’erreur pouvant être reçus lors de cette étape ainsi que les solutions à mettre en œuvre.

redirectionStatusCode Description
00 Cas normal qui doit être suivi du processus normal d’affichage de l’interface de gestion de wallet.
03 L’identifiant commerçant ou le contrat acquéreur ne sont pas valides.
12 Paramètres invalides. Vérifiez les paramètres de la requête.
30 Le format de la requête est invalide.
34 Problème de sécurité : par ex. le sceau calculé est incorrect.
40 Fonction non gérée.
99 Service temporairement indisponible.

4 cas sont à prendre en considération :

  • RedirectionStatusCode  = 00

Ce cas doit être suivi de la redirection de l’utilisateur vers la page de gestion de wallet.

  • RedirectionStatusCode  = 03, 12, 30, 34, 40

Codes d’erreur indiquant que la requête est incorrecte et doit être corrigée. Le processus doit alors être interrompu.

  • RedirectionStatusCode  = 99

Ce code indique un problème de disponibilité du service de gestion de wallet. Vous devez essayer de soumettre la requête de nouveau.

Champs génériques

Champ Présence A partir de la version Commentaires
customerId Facultatif WMR_WS_ 2.0
customerIpAddress Facultatif WMR_WS_ 2.0
customerLanguage Facultatif WMR_WS_ 2.0
interfaceVersion Obligatoire WMR_WS_ 2.0
merchantId Obligatoire WMR_WS_ 2.0
merchantSessionId Facultatif WMR_WS_ 2.0
merchantWalletId Obligatoire WMR_WS_ 2.0
normalReturnUrl Obligatoire WMR_WS_ 2.0
automaticResponseURL Facultatif WMR_WS_ 2.0
paymentMeanBrandList Facultatif WMR_WS_ 2.0
walletActionNameList Facultatif WMR_WS_ 2.0
requestDateTime Obligatoire WMR_WS_ 2.0 Date et heure d’envoi de la requête. La différence entre requestDateTime et la date et l’heure de réception de la requête par Sips ne doit pas excéder deux minutes. Sinon, la requête est refusée.
responseKeyVersion Facultatif WMR_WS_ 2.0
returnContext Facultatif WMR_WS_ 2.0
templateName Facultatif WMR_WS_ 2.0
billingAddress Facultatif WMR_WS_ 2.0 Voir la partie Containers
billingContact Facultatif WMR_WS_ 2.0 Voir la partie Containers
customerAddress Facultatif WMR_WS_ 2.0 Voir la partie Containers
customerContact Facultatif WMR_WS_ 2.0 Voir la partie Containers
customerData Facultatif WMR_WS_ 2.0 Voir la partie Containers
deliveryAddress Facultatif WMR_WS_ 2.0 Voir la partie Containers
deliveryContact Facultatif WMR_WS_ 2.0 Voir la partie Containers
fraudData Facultatif WMR_WS_ 2.0 Voir la partie Containers
holderAddress Facultatif WMR_WS_ 2.0 Voir la partie Containers
holderContact Facultatif WMR_WS_ 2.0 Voir la partie Containers
holderData Facultatif WMR_WS_ 2.0 Voir la partie Containers
paymentMeanData Facultatif WMR_WS_ 2.4 Voir la partie Containers
intermediateServiceProviderId Facultatif WMR_WS_ 2.2
seal Obligatoire WMR_WS_ 2.2
keyVersion Obligatoire WMR_WS_ 2.2
sealAlgorithm Facultatif WMR_WS_ 2.2
mandateId Facultatif WMR_WS_ 2.4
transactionActors Facultatif WMR_WS_ 2.4
responseEncoding Facultatif WMR_WS_ 2.5
merchantName Facultatif WMR_WS_ 2.6
merchantUrl Facultatif WMR_WS_ 2.6

Champs optionnels relatifs à l'adresse de facturation du client

Contenu de billingAddress

Champ A partir de la version Commentaires
addressAdditional1 WMR_WS_ 2.0
addressAdditional2 WMR_WS_ 2.0
addressAdditional3 WMR_WS_ 2.0
city WMR_WS_ 2.0
company WMR_WS_ 2.0
country WMR_WS_ 2.0
postBox WMR_WS_ 2.0
state WMR_WS_ 2.0
street WMR_WS_ 2.0
streetNumber WMR_WS_ 2.0
zipCode WMR_WS_ 2.0
businessName WMR_WS_ 2.4

Contenu de billingContact

Champ A partir de la version Commentaires
email WMR_WS_ 2.0
firstname WMR_WS_ 2.0
gender WMR_WS_ 2.0
lastname WMR_WS_ 2.0
mobile WMR_WS_ 2.0
phone WMR_WS_ 2.0
title WMR_WS_ 2.0
initials WMR_WS_ 2.2
legalId WMR_WS_ 2.4
positionOccupied WMR_WS_ 2.4

Champs optionnels relatifs à l'adresse de livraison du client

Contenu de deliveryAddress

Champ A partir de la version Commentaires
addressAdditional1 WMR_WS_ 2.0
addressAdditional2 WMR_WS_ 2.0
addressAdditional3 WMR_WS_ 2.0
city WMR_WS_ 2.0
company WMR_WS_ 2.0
country WMR_WS_ 2.0
postBox WMR_WS_ 2.0
state WMR_WS_ 2.0
street WMR_WS_ 2.0
streetNumber WMR_WS_ 2.0
zipCode WMR_WS_ 2.0
businessName WMR_WS_ 2.4

Contenu de deliveryContact

Champ A partir de la version Commentaires
email WMR_WS_ 2.0
firstname WMR_WS_ 2.0
gender WMR_WS_ 2.0
lastname WMR_WS_ 2.0
mobile WMR_WS_ 2.0
phone WMR_WS_ 2.0
title WMR_WS_ 2.0
initials WMR_WS_ 2.2
legalId WMR_WS_ 2.4
positionOccupied WMR_WS_ 2.4

Champs optionnels relatifs à la fraude

Contenu de fraudData

Champ A partir de la version Commentaires
bypassCtrlList WMR_WS_ 2.0
bypassInfoList WMR_WS_ 2.0
bypass3DS WMR_WS_ 2.0
allowedCardCountryList WMR_WS_ 2.0
deniedCardCountryList WMR_WS_ 2.0
allowedIpCountryList WMR_WS_ 2.0
deniedIpCountryList WMR_WS_ 2.0
allowedCardArea WMR_WS_ 2.0
deniedCardArea WMR_WS_ 2.0
allowedIpArea WMR_WS_ 2.0
deniedIpArea WMR_WS_ 2.0
riskManagementDynamicSettingList WMR_WS_ 2.0 Liste de conteneur riskManagementDynamicSetting . Voir la partie Containers

Contenu de riskManagementDynamicSetting

Champ A partir de la version Commentaires
riskManagementDynamicParam WMR_WS_ 2.0
riskManagementDynamicValue WMR_WS_ 2.0

Champs optionnels relatifs aux données du titulaire de la carte

Contenu de holderAddress

Champ A partir de la version Commentaires
addressAdditional1 WMR_WS_ 2.0
addressAdditional2 WMR_WS_ 2.0
addressAdditional3 WMR_WS_ 2.0
city WMR_WS_ 2.0
company WMR_WS_ 2.0
country WMR_WS_ 2.0
postBox WMR_WS_ 2.0
state WMR_WS_ 2.0
street WMR_WS_ 2.0
streetNumber WMR_WS_ 2.0
zipCode WMR_WS_ 2.0
businessName WMR_WS_ 2.4

Contenu de holderContact

Champ A partir de la version Commentaires
email WMR_WS_ 2.0
firstname WMR_WS_ 2.0
gender WMR_WS_ 2.0
lastname WMR_WS_ 2.0
mobile WMR_WS_ 2.0
phone WMR_WS_ 2.0
title WMR_WS_ 2.0
initials WMR_WS_ 2.2
legalId WMR_WS_ 2.4
positionOccupied WMR_WS_ 2.4

Contenu de holderData

Champ A partir de la version Commentaires
birthCity WMR_WS_ 2.0
birthCountry WMR_WS_ 2.0
birthDate WMR_WS_ 2.0
birthZipCode WMR_WS_ 2.0
nationalityCountry WMR_WS_ 2.0
newPassword WMR_WS_ 2.0
password WMR_WS_ 2.0

Champs optionnels relatifs aux moyens de paiement

Contenu de paymentMeanData

Champ A partir de la version Commentaires
sdd WMR_WS_ 2.4 Voir la partie Containers

Contenu de sdd

Champ A partir de la version Commentaires
mandateAuthentMethod WMR_WS_ 2.4
mandateCertificationType WMR_WS_ 2.4

Paramétrer la requête de gestion du wallet

Voici un exemple de paramétrage de la requête de gestion du wallet pour chaque fonctionnalité disponible dans Sips Walletpage SOAP . Le détail de ces fonctionnalités est décrit dans le guide des fonctionnalités, le guide OneClick et le guide Subscription.

Restriction des fonctionnalités client de gestion du wallet

Par défaut, le client a accès à l’ensemble des fonctionnalités de gestion du wallet. Pour restreindre l’accès, il faut préciser la liste des fonctionnalités souhaitées dans le champ WalletActionNameList , comme ici pour ne permettre que d’ajouter ou modifier les moyens de paiement dans son wallet :

      <walletActionNameList>
 <walletActionName>ADDPM</walletActionName>
 <walletActionName>UPDATEPM</walletActionName>
</walletActionNameList>
    

Restriction dynamique des moyens de paiement

Il faut filtrer ceux qui seront disponibles pour être ajoutés dans le wallet grâce au champ paymentMeanBrandList :

      <paymentMeanBrandList>
       <paymentMeanBrand>VISA</paymentMeanBrand>
       <paymentMeanBrand>PAYPAL</paymentMeanBrand>
</paymentMeanBrandList>

    

Identification du wallet du client

L’identifiant du wallet du client doit être renseigné dans le champ merchantWalletId .
      <merchantWalletId>1205987</merchantWalletId>
    

Prestataire agissant pour le compte d’un commerçant

Vous devez passer l’identifiant du prestataire dans la requête, dans le champ intermediateServiceProvider , et utiliser la clé secrète de ce dernier pour calculer la donnée Seal  :

      <intermediateServiceProviderId>241891</intermediateServiceProviderId>
    

Traiter la réponse

Deux types de réponse sont prévus. Bien que les protocoles, formats et contenus des deux réponses soient exactement les mêmes, elles doivent être gérées de manière différente car elles répondent à deux besoins différents.

Les réponses sont des réponses HTTP(S) POST envoyées aux URL normalReturnUrl (obligatoire - réponse manuelle) et automaticResponseUrl (optionnelle - réponse automatique) précisées dans la requête.

Vous devez mettre en place le système permettant de décoder ces réponses, afin de connaître le résultat de requête.

Les quatre données suivantes sont définies dans les réponses :

Données Notes/règles
Data Concaténation des champs en réponse.
Encode Type d’encodage utilisé pour la donnée Data . Ce champ est valorisé avec le champ responseEncoding de la requête.
Seal Signature du message réponse.
InterfaceVersion Version de l’interface du connecteur.

Si la valeur du champ Encode est “base64” ou “base64url”, la donnée Data doit-être décodée en Base64/Base64Url pour retrouver la chaîne des champs concaténée. La chaîne concaténée est structurée comme suit : clé1=valeur1|clé2=valeur2… Le sceau (donnée Seal ) des 2 réponses est « hashé » avec le même algorithme utilisé en entrée et fourni dans le champ sealAlgorithm . Si aucune valeur n’a été définie, la valeur SHA-256 est utilisée par défaut.

Note: pour qu’un sceau soit calculé avec l'algorithme HMAC-SHA-256, les paramètres d'entrée de la requête doivent contenir le champ sealAlgorithm avec la valeur suivante : “HMAC-SHA-256”.

La valeur de la donnée Seal est calculée comme suit :

Pour l'algorithme HMAC-SHA :

  • utilisation de la clé secrète partagée pour générer la variante HMAC du message ;
  • utilisation de la donnée Data uniquement (encodée si l’option correspondante est choisie) ;
  • codage UTF-8 des données constituant le résultat de l’opération précédente ;
  • « Hashage » HMAC-SHA des octets obtenus.

Cette procédure peut être résumée comme suit :

      HMAC-SHA256( UTF-8(Data), UTF-8(secretKey))
    

Pour l’algorithme SHA-256 (bien que celui-ci soit la valeur par défaut, cet algorithme n’est plus recommandé à ce jour) :

  • concaténation de la donnée Data et de la clé secrète (encodée si l’option correspondante est choisie) ;
  • codage UTF-8 des données constituant le résultat de l’opération précédente ;
  • « Hashage » SHA256 des octets obtenus.

Cette procédure peut être résumée comme suit :

      SHA256( UTF-8(Data+secretKey ) )
    

Renseigner l’URL de la réponse manuelle

Le principal objectif de la réponse manuelle est de rediriger le client vers votre site web en indiquant le résultat de la gestion de wallet.

La page principale de WL Sips contient le bouton « Retour » avec un lien de redirection vers votre site. Lorsque le client clique sur ce bouton, le serveur WL Sips le redirige vers l’adresse URL contenue dans le champ normalReturnUrl fourni dans la requête. La redirection est une requête HTTP(S) POST qui contient les données de la réponse. Il est de votre responsabilité de récupérer ces paramètres et de vérifier la signature pour ainsi assurer l’intégrité des données de la réponse. De plus, vous avez pour responsabilité d’afficher à votre client les messages pertinents relatifs aux détails de la réponse.

Ce champ normalReturnUrl est également utilisé pour tous les résultats de paiement (annulation, refus...) afin de rediriger vers votre site.

Il est important de noter qu’il est impossible de garantir la réception de la réponse, celle-ci étant envoyée par le navigateur web du client. Tout d’abord, le client a la possibilité de ne pas cliquer sur le lien. Ensuite, la connexion qu’il utilise peut tout simplement avoir un problème et bloquer la transmission de cette réponse. Par conséquent, celle-ci ne peut pas constituer la base unique pour vos processus métier.

Note: la version actuelle d’ InterfaceVersion est  HP_ 2.6 . Veuillez consultez le dictionnaire de données WL Sips pour une description complète des paramètres inclus dans la réponse.

Renseigner l’URL de la réponse automatique

La réponse automatique est envoyée seulement si le champ automaticResponseUrl a été envoyé dans la requête de gestion du wallet. Si tel est le cas, le serveur WL Sips envoie une réponse HTTP(S) POST à l’adresse URL reçue.

Les champs de la réponse automatique sont identiques à ceux de la réponse manuelle. La seule différence entre les deux procédures est que la réponse automatique est envoyée directement par le serveur WL Sips sans passer par le navigateur Web du client. Par conséquent, elle est bien plus fiable car elle est toujours envoyée. Le serveur WL Sips n’attend aucune réponse après la transmission de la réponse automatique.

Il vous appartient de récupérer les différentes données de la réponse, vérifier la signature pour vous assurer de l’intégrité des champs de la réponse et, par conséquent, mettre à jour votre back office.

Note: la version actuelle d’ InterfaceVersion est  HP_ 2.6 . Veuillez consultez le dictionnaire de données WL Sips pour une description complète des paramètres inclus dans la réponse.

Résoudre les problèmes de réception des réponses

Vous trouverez ci-dessous une liste des problèmes les plus couramment observés qui bloquent la réception des réponses automatiques et manuelles. Assurez-vous de les avoir vérifiés avant d’appeler le service d’assistance technique :

  • vérifiez si les adresses URL de réponse sont fournies dans la requête de gestion du wallet et si elles sont valides. Pour faire cela, vous pouvez tout simplement les copier/coller dans votre navigateur ;
  • les adresses URL fournies doivent être accessibles depuis l’extérieur, c'est-à-dire de l’Internet. Le contrôle d’accès (identifiant/mot de passe ou filtre IP) ou le pare-feu peuvent bloquer l’accès à votre serveur ;
  • l’accès aux adresses URL de réponse doit être confirmé dans le journal des notifications de votre serveur Web ;
  • si vous utilisez un port non standard, il doit être compris entre 80 et 9999 pour assurer la compatibilité avec WL Sips .

Dans certains cas d’erreurs, le serveur WL Sips n’est pas capable de signer le message de réponse. Cela s’applique, par exemple, à l’erreur « MerchantID inconnu » et au cas où la clé secrète est inconnue de WL Sips . Pour ces raisons, le serveur de paiement envoie une réponse sans signature dans le champ Seal .

Récupérer les champs des réponses

Le contenu des réponses Web automatiques et manuelles de Sips Walletpage est identique.

Nom du champ Version Commentaires
merchantId WMR_WS_ 2.0
keyVersion WMR_WS_ 2.0
merchantWalletId WMR_WS_ 2.0
merchantSessionId WMR_WS_ 2.0
customerId WMR_WS_ 2.0
customerIpAddress WMR_WS_ 2.0
returnContext WMR_WS_ 2.0
walletCreationDateTime WMR_WS_ 2.0
walletLastActionDateTime WMR_WS_ 2.0
walletPaymentMeanDataList WMR_WS_ 2.0 Liste des moyens de paiement du wallet (Cf. tableau ci-dessous : champs de l’élément walletPaymentMeanData ).
customerCompanyName WMR_WS_ 2.4
customerBusinessName WMR_WS_ 2.4
customerLegalId WMR_WS_ 2.4
customerPositionOccupied WMR_WS_ 2.4
Champ Version Commentaires
paymentMeanId WMR_WS_ 2.0
paymentMeanAlias WMR_WS_ 2.0
paymentMeanBrand WMR_WS_ 2.0
maskedPan WMR_WS_ 2.0
panExpiryDate WMR_WS_ 2.0
mandateId WMR_WS_ 2.4
transactionActors WMR_WS_ 2.4
Note: les réponses manuelle et automatique sont encodées soit en base64, soit en base64url .

Analyser la réponse de gestion du wallet

Si vous procédez à une authentification par sceau électronique (seal), vous devez impérativement vérifier que le sceau reçu correspond bien au sceau que vous recalculez avec les champs de la réponse.

Si le sceau reçu ne correspond pas au sceau que vous recalculez, l’état de la session de gestion de wallet est considéré comme inconnu, veuillez contacter le support.

État Champs de la réponse Action à réaliser
Opération de gestion wallet prise en compte walletLastActionDateTime renseigné avec la date/heure courante

walletPaymentMeanDataList contient les moyens de paiement du wallet après mise à jour

Stockez dans votre base client les données suivantes du wallet :
  • paymentMeanAlias
  • paymentMeanId
  • paymentMeanBrand
  • PanExpiryDate
  • maskedPAN
Opération de gestion wallet pas prise en compte

walletLastActionDateTime pas renseigné avec date/heure courante

walletPaymentMeanDataList contient les moyens de paiement du wallet

Si la mise jour wallet est requise alors resoumettez une requête.

Étape 3 : tester sur l’environnement de simulation

Une fois le développement de la connexion à Sips Walletpage réalisé, vous pouvez effectuer un test sur le serveur Sips Walletpage de simulation.

URL de simu du serveur https://payment-webinit.simu.sips-atos.com/services/v2/walletManagementInit

Pour effectuer ce test, il faut utiliser les identifiants en fonction du mode d’identification des transactions que vous souhaitez :

Table 1. transactionReference généré par le commerçant
champ Valeur
ID du commerçant (merchantId) 002001000000001
Version de la clé (keyVersion) 1
Clé secrète 002001000000001_KEY1
Table 2. transactionReference généré par WL Sips
champ Valeur
ID du commerçant (merchantId) 002001000000002
Version de la clé (keyVersion) 1
Clé secrète 002001000000002_KEY1
Table 3. transactionId généré par le commerçant
champ Valeur
ID du commerçant (merchantId) 002001000000003
Version de la clé (keyVersion) 1
Clé secrète 002001000000003_KEY1
Table 4. transactionId généré par WL Sips
champ Valeur
ID du commerçant (merchantId) 002001000000004
Version de la clé (keyVersion) 1
Clé secrète 002001000000004_KEY1
Note: dans l’environnement de simulation, toutes les opérations sont simulées. Il n’y a pas d’interaction avec la base de données wallet pour les opérations d’ajout ou de suppression de moyen de paiement.

Tester l’ajout des cartes dans le wallet

Si vous souhaitez enregistrer une carte, vous êtes redirigé vers la page de saisie des informations de la carte où vous pouvez saisir les données détaillées de votre carte.

Les règles de simulation suivantes s’appliquent :

  • le PAN doit comporter de 15 à 19 chiffres (selon le moyen de paiement utilisé) ;
  • les six premiers chiffres du PAN déterminent le type de carte, conformément au tableau ci-dessous ;
Type de carte Début du numéro de carte
AMEX 340000
VPAY 400000
VISA 410000
CB 420000
Cartes co-badgées CB et VISA 430000
Cartes co-badgées CB et VPAY 440000
Cartes co-badgées CB et VISA_ELECTRON 450000
Cartes co-badgées VISA et MASTERCARD 460000
MASTERCARD 510000
MAESTRO 500000
Cartes co-badgées CB et MASTERCARD 520000
Cartes co-badgées CB et MAESTRO 530000
  • vous pouvez simuler la réussite ou l’échec de l’ajout d’une carte en faisant votre choix parmi tous les codes de réponse (cf. dictionnaire de données) et en modifiant les deux derniers chiffres. Seul le code réponse ‘00’ simule le succès de l’ajout.

Exemple : si vous utilisez le numéro de carte 4100 00 00 0000 00 05 , la carte est identifiée comme VISA et l’ajout ne se fait pas (code réponse WL Sips 0 5 ).

Note: les cartes co-badgées peuvent être utilisées avec chacune des marques définies dans le tableau.

Aussi, toutes les cartes sont enrôlées 3-D Secure, vous êtes redirigé vers le serveur de simulation 3-D Secure sur lequel vous choisissez le résultat désiré de l’authentification 3-D Secure.

Étape 4 : valider le passage en production

Une fois la connexion de votre site Web à Sips Walletpage SOAP testée, vous êtes à présent en mesure de valider la connexion à Sips Walletpage SOAP de production.

Au préalable, nous conseillons d’isoler votre site Web du public pour éviter que des clients ne génèrent des requêtes pendant cette phase de validation.

Si vous souhaitez personnaliser vos pages de paiement et de gestion de wallet, vous pouvez utiliser notre outil CustomPages , permettant de tester et visualiser le rendu des pages. Pour cela, merci de vous référer à la documentation CustomPages afin d’utiliser l’outil.

Pour basculer sur le serveur de production, vous devez changer l’URL pour vous connecter au serveur WL Sips de production en utilisant les identifiants merchantId , secretKey et keyVersion reçus lors l’inscription.

URL https://payment-webinit.sips-atos.com/services/v2/walletManagementInit
merchantId Identifiant de la boutique reçu par mail
SecretKey Clé secrète que vous récupérez via l’extranet Sips Download
keyVersion Version clé secrète récupérée sur Sips Download (logiquement 1 pour la 1ère clé)
Note: une erreur fréquente est d’oublier un de ces 4 paramètres, ce qui conduit systématiquement à une erreur.

Comment valider le bon fonctionnement en production

  • Initiez un wallet en ajoutant une première carte dedans.
  • Vérifiez que le wallet a bien été créé.
  • Ajoutez une deuxième carte dans un wallet existant si l’option multicarte a été souscrite.
  • Vérifiez que la 2e carte a bien été ajoutée.

Étape 5 : Démarrer en production

Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’ajouter des moyens de paiement dans leur wallet.