WL SIPS DOCS

Release 21.4

aller directement au contenu
Rechercher par mots clés

Sips Paypage SOAP

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

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

Ce document est destiné aux commerçants qui souhaitent souscrire à l’offre WL Sips et utiliser un connecteur à base d'échanges SOAP entre leur site Web et les serveurs de paiement Sips Paypage SOAP.

C’est un guide d’implémentation qui s’adresse à votre équipe technique.

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.

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

Lors de votre inscription, Worldline met à disposition sur le MEX (voir la notice de renouvellement des clés secrètes), 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 le MEX (voir la « notice de renouvellement des clés secrètes »).

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 le paiement avec Sips Paypage SOAP

Le principe général d’une cinématique de paiement est le suivant :


comprendre-paiement-paypage-json-soap

1. Lorsque le client procède au paiement, une requête de paiement doit être envoyée au connecteur Sips Paypage SOAP. Worldline vous fournit l’URL de ce connecteur. 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 les pages de paiement WL Sips. Le client doit saisir les informations du moyen de paiement pour que le serveur de paiement WL Sips prenne en charge la transaction. Il convient de noter que les détails du paiement peuvent être saisis directement sur le serveur qui propose le moyen de paiement (par exemple dans le cas de PayPal ou d’un mandat Sepa). À la fin du processus de paiement, qu’il soit réussi ou non, deux réponses sont créées et envoyées à l’adresse URL précisée lors du 1er flux.

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

3. Les réponses manuelles sont envoyées sous format HTTP(S) POST par le serveur de paiement à l’URL de réponse manuelle. Cette URL est précisée dans la requête de paiement et est utilisée lorsque le client clique sur le bouton « Continuer » de la page de paiement. Elle est la page de destination vers laquelle le client est redirigé à la fin du paiement. Comme il n’y a aucune garantie que le client clique sur ce bouton, vous n’avez aucune garantie de recevoir la réponse manuelle.

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 paiement WL Sips mais cette fois-ci moyennant l’URL de réponse automatique précisée dans la requête de paiement. Cela signifie que vous recevez la réponse dès que le paiement est effectué dans les pages de paiement WL Sips. Cependant, en cas d'abandon du client, vous recevez la réponse automatique, environ 15 minutes après la redirection du client sur le serveur de paiement WL Sips.

Note: si vous n'avez pas l'option "Nouvelle tentative de paiement" (voir partie "Nouvelle tentative de paiement dans le document "Guide de Configuration des fonctionnalités"), si le paiement a échoué, et dès que le client est redirigé vers votre site Web, il n’est plus possible de revenir aux pages de paiement WL Sips pour tenter de payer à nouveau ou pour corriger les données de carte. Le rôle de votre site Web est d’initialiser une nouvelle requête de paiement, en commençant par l’appel au connecteur Sips Paypage.

Afin d’inscrire votre boutique, vous devez remplir le formulaire d’inscription envoyé par Worldline et le retourner à ce dernier.

Lors de la saisie du formulaire, vous désignez un contact administratif et un contact technique afin que Worldline puisse vous communiquer les informations nécessaires pour démarrer votre boutique.

Worldline procède alors à l’enregistrement de la boutique et vous retourne votre identifiant commerçant (merchantId) ainsi que vos identifiants et mots de passe Sips Download (récupération de la clé secrète) et Sips Office Extranet (gestion de caisse) par mail.

Note: pour Sips Office Extranet, l’identifiant et le mot de passe sont envoyés au contact administratif. Pour Sips Download, l’identifiant est envoyé au contact administratif et le mot de passe au contact technique.

L’inscription de la boutique n’est pas nécessaire pour commencer à intégrer le connecteur et à tester la connexion sur l’environnement de simulation. Vous pouvez ne demander l’inscription de votre boutique qu’au moment de faire les tests en production.

La requête de paiement consiste en un appel vers un service Web REST (SOAP) situé sur la plateforme de paiement.

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

La valeur du champ interfaceVersion doit être fixée à IR_WS_2.38.

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

Exemple d’une requête de paiement d’un montant de 52,50 euros :

<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
  <soapenv:Body>
    <urn:paymentWebInit xmlns:urn='urn:sips:cn:contract:payment:v2'>
      <urn:input>
        <urn:amount>5250</urn:amount>
        <urn:currencyCode>978</urn:currencyCode>
        <urn:interfaceVersion> IR_WS_2.20</urn:interfaceVersion>
        <urn:merchantId>011223744550001</urn:merchantId>
        <urn:normalReturnUrl> http://www.normalreturnurl.com </urn:normalReturnUrl>
        <urn:orderChannel>INTERNET</urn:orderChannel>
        <urn:responseKeyVersion>1</urn:responseKeyVersion>
        <urn:transactionReference>TREF0808151333</urn:transactionReference>
        <urn:keyVersion>3</urn:keyVersion>
      <urn:seal>3a02205859ffd2eff4d7dd015ce01fda11d80f03fa88e2caa188c5eea5a42c61</urn:seal></urn:input>
    </urn:paymentWebInit>
  </soapenv:Body>
</soapenv:Envelope>

Certains champs de la requête de paiement ne sont obligatoires que :

  • lors de l'utilisation de certains moyens de paiement ; veuillez consulter le guide du moyen de paiement concerné pour savoir quels champs sont obligatoires ;
  • en fonction de la configuration de votre boutique ; veuillez consulter le guide de configuration des fonctionnalités pour savoir quels champs sont obligatoires ;
  • dans certains cas d'usages (ex : paiement récurrent) ; veuillez consulter le guide de configuration des fonctionnalités pour savoir quels champs sont obligatoires.

Ces champs sont désignés avec la mention « conditionnel ».

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.

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.

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))
Attention: par défaut, le sceau est calculé avec l'algorithme HMAC-SHA-256, dont nous recommandons vivement l'utilisation.

Si toutefois vous souhaitiez calculer le sceau avec l'algorithme plus ancien SHA-256, les paramètres d'entrée de la requête doivent contenir le champ sealAlgorithm avec la valeur suivante : “SHA-256”.

  • 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();
            }
    
        }
    }

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:paymentWebInit>
         <urn:input>
            <urn:amount>2500</urn:amount>
            <urn:urn:automaticResponseUrl>https://automatic-response-url.fr/</urn:urn:automaticResponseUrl>
            <urn:normalReturnUrl>https://normal-return-url/</urn:normalReturnUrl>
            <urn:captureDay>0</urn:captureDay>
            <urn:captureMode>AUTHOR_CAPTURE</urn:captureMode>
            <urn:currencyCode>978</urn:currencyCode>
            <urn:customerContact>
                <urn:email>customer@email.com</urn:email>
            </urn:customerContact>
            <urn:interfaceVersion>IR_WS_2.22</urn:interfaceVersion>
            <urn:keyVersion>1</urn:keyVersion>
            <urn:merchantId>011223344550000</urn:merchantId>
            <urn:orderChannel>INTERNET</urn:orderChannel>
            <urn:orderId>ORD101</urn:orderId>
            <urn:returnContext>ReturnContext</urn:returnContext>
            <urn:transactionOrigin>SO_WEBAPPLI</urn:transactionOrigin>
            <urn:transactionReference>TREFEXA2012</urn:transactionReference>
            <urn:seal>322b943d833417c1570e0a282641e8e29d6a5b968c9b846694b5610e18ab5b81</urn:seal>
         </urn:input>
      </urn:paymentWebInit>

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

2500https://automatic-response-url.fr/0AUTHOR_CAPTURE978customer@email.comIR_WS_2.22011223344550000https://normal-return-url/INTERNETORD101ReturnContextSO_WEBAPPLITREFEXA2012

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

secret123

Le seal attendu est :

322b943d833417c1570e0a282641e8e29d6a5b968c9b846694b5610e18ab5b81

Voici ci-dessous un exemple de requête au format SOAP :

<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
  <soapenv:Body>
    <urn:paymentWebInit xmlns:urn='urn:sips:cn:contract:payment:v2'>
      <urn:input>
        <urn:amount>5250</urn:amount>
        <urn:currencyCode>978</urn:currencyCode>
        <urn:interfaceVersion> IR_WS_2.20</urn:interfaceVersion>
        <urn:merchantId>011223744550001</urn:merchantId>
        <urn:normalReturnUrl> http://www.normalreturnurl.com </urn:normalReturnUrl>
        <urn:orderChannel>INTERNET</urn:orderChannel>
        <urn:responseKeyVersion>1</urn:responseKeyVersion>
        <urn:transactionReference>TREF0808151333</urn:transactionReference>
        <urn:keyVersion>3</urn:keyVersion>
      <urn:seal>3a02205859ffd2eff4d7dd015ce01fda11d80f03fa88e2caa188c5eea5a42c61</urn:seal></urn:input>
    </urn:paymentWebInit>
  </soapenv:Body>
</soapenv:Envelope>

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

Nom du champ Description
redirectionData Token de la requête à fournir lors de la redirection vers les pages de de paiement.
redirectionStatusCode Liste des codes réponse possibles.
redirectionStatusMessage Court message donnant le statut de l’initialisation.
redirectionUrl URL des pages de paiement 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 du paiement 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 paiement WL Sips.

Pour rediriger le client vers les pages de paiement, 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 fournie dans le champ redirectionUrl.

Ci-dessous un exemple de formulaire à soumettre 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>

Tous les champs reçus par Sips Paypage 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 Situation normale suivie du processus normal d'affichage des pages de paiement.
03 L’identifiant commerçant ou le contrat acquéreur ne sont pas valides.
12 Les paramètres de la transaction sont 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.
94 La transaction existe déjà
99 Service temporairement indisponible.

4 cas sont possibles :

  • RedirectionStatusCode = 00

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

  • RedirectionStatusCode = 03, 12, 30, 34

Ces codes d’erreur indiquent que la requête comporte un problème qui doit être résolu. Le processus de paiement doit alors être interrompu.

  • RedirectionStatusCode = 94

La référence de transaction a déjà été utilisée. Vous devez réessayer avec une autre référence de transaction.

  • RedirectionStatusCode = 99

Problème de disponibilité du service de paiement. Vous devez essayer de renvoyer la requête. Il convient d’utiliser une nouvelle référence de transaction pour éviter un code de réponse 94.

Champ Présence A partir de la version Commentaires
amount Obligatoire IR_WS_2.0
automaticResponseUrl Facultatif IR_WS_2.0
captureDay Facultatif IR_WS_2.0
captureMode Facultatif IR_WS_2.0
currencyCode Obligatoire IR_WS_2.0
customerEmail Facultatif IR_WS_2.0
customerId Facultatif IR_WS_2.0
customerLanguage Facultatif IR_WS_2.0
fraudData Facultatif IR_WS_2.0 Voir la partie Containers
hashSalt1 Facultatif IR_WS_2.0
hashSalt2 Facultatif IR_WS_2.0
hashAlgorithm1 Facultatif IR_WS_2.0
hashAlgorithm2 Facultatif IR_WS_2.0
interfaceVersion Obligatoire IR_WS_2.0
merchantId Obligatoire IR_WS_2.0
merchantSessionId Facultatif IR_WS_2.0
merchantTransactionDateTime Facultatif IR_WS_2.0
merchantWalletId Facultatif IR_WS_2.0
normalReturnUrl Obligatoire IR_WS_2.0
orderChannel Obligatoire IR_WS_2.0
orderId Facultatif IR_WS_2.0
paymentMeanBrandList Facultatif IR_WS_2.0
paymentMeanData Facultatif IR_WS_2.0 Voir la partie Containers
responseKeyVersion Facultatif IR_WS_2.0
returnContext Facultatif IR_WS_2.0
templateName Facultatif IR_WS_2.0
transactionActors Facultatif IR_WS_2.0
transactionReference Conditionnel IR_WS_2.0 Obligatoire si vous n'utilisez pas le s10TransactionReference ou que WL Sips ne le calcule pas pour pour vous, dépend de votre configuration commerçant
transactionOrigin Facultatif IR_WS_2.0
invoiceReference Facultatif IR_WS_2.0
bypassReceiptPage Facultatif IR_WS_2.0
customerIpAddress Facultatif IR_WS_2.0
customerTimestampIpAddress Facultatif IR_WS_2.26
bypassDcc Facultatif IR_WS_2.0
instalmentData Facultatif IR_WS_2.0 Voir la partie Containers
billingAddress Facultatif IR_WS_2.0 Voir la partie Containers
billingContact Facultatif IR_WS_2.0 Voir la partie Containers
customerAddress Facultatif IR_WS_2.0 Voir la partie Containers
customerContact Facultatif IR_WS_2.0 Voir la partie Containers
deliveryAddress Facultatif IR_WS_2.0 Voir la partie Containers
deliveryContact Facultatif IR_WS_2.0 Voir la partie Containers
holderAddress Facultatif IR_WS_2.0 Voir la partie Containers
holderContact Facultatif IR_WS_2.0 Voir la partie Containers
customerData Facultatif IR_WS_2.0 Voir la partie Containers
paymentPattern Conditionnel IR_WS_2.0
statementReference Facultatif IR_WS_2.0
authenticationData Facultatif IR_WS_2.0 Voir la partie Containers
mandateId Facultatif IR_WS_2.0
billingFirstDate Facultatif IR_WS_2.0
customer3DSTransactionDate Facultatif IR_WS_2.0
customerBillingNb Facultatif IR_WS_2.0
customerDeliverySuccessFlag Facultatif IR_WS_2.0
customerPhoneValidationMethod Facultatif IR_WS_2.0
customerRegistrationDateOnline Facultatif IR_WS_2.0
customerRegistrationDateProxi Facultatif IR_WS_2.0
deliveryFirstDate Facultatif IR_WS_2.0
evidenceAcquisitionDate Facultatif IR_WS_2.0
evidenceNumber Facultatif IR_WS_2.0
evidenceType Facultatif IR_WS_2.0
valueDate Facultatif IR_WS_2.0
deliveryData Facultatif IR_WS_2.6 Voir la partie Containers
shoppingCartDetail Facultatif IR_WS_2.6 Voir la partie Containers
holderData Facultatif IR_WS_2.6 Voir la partie Containers
s10TransactionReference Conditionnel IR_WS_2.7 Obligatoire si vous n'utilisez pas le transactionReference ou que WL Sips ne le calcule pas pour pour vous, dépend de votre configuration commerçant. Voir la partie Containers
holderAdditionalReference Facultatif IR_WS_2.9
riskManagementCustomDataList Facultatif IR_WS_2.9 Liste de conteneur riskManagementCustomData. Voir la partie Containers
intermediateServiceProviderId Facultatif IR_WS_2.10
seal Obligatoire IR_WS_2.0
keyVersion Obligatoire IR_WS_2.0
sealAlgorithm Facultatif IR_WS_2.10
paypageData Facultatif IR_WS_2.11 Voir la partie Containers
subMerchantId Facultatif IR_WS_2.15
subMerchantShortName Facultatif IR_WS_2.15
subMerchantCategoryCode Facultatif IR_WS_2.15
subMerchantLegalId Facultatif IR_WS_2.15
subMerchantAddress Facultatif IR_WS_2.15 Voir la partie Containers
orderContext Facultatif IR_WS_2.16 Voir la partie Containers
travelContext Facultatif IR_WS_2.16 Voir la partie Containers
responseEncoding Facultatif IR_WS_2.19
subMerchantName Facultatif IR_WS_2.20
subMerchantContractNumber Facultatif IR_WS_2.20
customerAccountHistoric Facultatif IR_WS_2.21 Voir la partie Containers
merchantName Facultatif IR_WS_2.23 Permet de modifier le nom affiché sur la page d'authentification 3-D Secure
merchantUrl Facultatif IR_WS_2.29 Permet de modifier l'url du site marchand affiché sur la page d'authentification 3-D Secure

Contenu de authenticationData

Champ A partir de la version Commentaires
cardAuthPolicy IR_WS_2.0 Voir la partie Containers
issuerWalletAuthPolicy IR_WS_2.0 Voir la partie Containers
authentAmount IR_WS_2.37

Contenu de cardAuthPolicy

Champ A partir de la version Commentaires
checkAVS IR_WS_2.0
ignoreCSCCheckResult IR_WS_2.0
ignorePostcodeCheckResult IR_WS_2.0
ignoreAddressCheckResult IR_WS_2.0

Contenu de issuerWalletAuthPolicy

Champ A partir de la version Commentaires
check3DS IR_WS_2.0
checkCSC IR_WS_2.0

Contenu de billingAddress

Champ A partir de la version Commentaires
addressAdditional1 IR_WS_2.0
addressAdditional2 IR_WS_2.0
addressAdditional3 IR_WS_2.0
city IR_WS_2.0
company IR_WS_2.0
country IR_WS_2.0
postBox IR_WS_2.0
state IR_WS_2.0
street IR_WS_2.0
streetNumber IR_WS_2.0
zipCode IR_WS_2.0
businessName IR_WS_2.17

Contenu de billingContact

Champ A partir de la version Commentaires
email IR_WS_2.0
firstname IR_WS_2.0
gender IR_WS_2.0
lastname IR_WS_2.0
mobile IR_WS_2.0
phone IR_WS_2.0
title IR_WS_2.0
initials IR_WS_2.11
legalId IR_WS_2.17
positionOccupied IR_WS_2.17
workPhone IR_WS_2.21

Contenu de customerAccountHistoric

Champ A partir de la version Commentaires
creationDate IR_WS_2.21
numberOfAttemptsAddCard24Hours IR_WS_2.21
numberOfPurchase IR_WS_2.26
numberOfPurchase180Days IR_WS_2.21
numberOfTransaction24Hours IR_WS_2.21
suspiciousActivityIndicator IR_WS_2.21
firstPurchaseDate IR_WS_2.24
lastPurchaseDate IR_WS_2.24
changeDate IR_WS_2.27
passwordChangeDate IR_WS_2.27
numberOfTransactionYear IR_WS_2.27
addPaymentMeanDate IR_WS_2.27
customerAccountId IR_WS_2.27

Contenu de customerAddress

Champ A partir de la version Commentaires
addressAdditional1 IR_WS_2.0
addressAdditional2 IR_WS_2.0
addressAdditional3 IR_WS_2.0
city IR_WS_2.0
company IR_WS_2.0
country IR_WS_2.0
postBox IR_WS_2.0
state IR_WS_2.0
street IR_WS_2.0
streetNumber IR_WS_2.0
zipCode IR_WS_2.0
businessName IR_WS_2.17

Contenu de customerContact

Champ A partir de la version Commentaires
email IR_WS_2.0
firstname IR_WS_2.0
gender IR_WS_2.0
lastname IR_WS_2.0
mobile IR_WS_2.0
phone IR_WS_2.0
title IR_WS_2.0
initials IR_WS_2.11
legalId IR_WS_2.17
positionOccupied IR_WS_2.17
workPhone IR_WS_2.21

Contenu de customerData

Champ A partir de la version Commentaires
birthCity IR_WS_2.0
birthCountry IR_WS_2.0
birthDate IR_WS_2.0
birthZipCode IR_WS_2.0
nationalityCountry IR_WS_2.0
newPassword IR_WS_2.0
password IR_WS_2.0
maidenName IR_WS_2.18

Contenu de deliveryAddress

Champ A partir de la version Commentaires
addressAdditional1 IR_WS_2.0
addressAdditional2 IR_WS_2.0
addressAdditional3 IR_WS_2.0
city IR_WS_2.0
company IR_WS_2.0
country IR_WS_2.0
postBox IR_WS_2.0
state IR_WS_2.0
street IR_WS_2.0
streetNumber IR_WS_2.0
zipCode IR_WS_2.0
businessName IR_WS_2.17

Contenu de deliveryContact

Champ A partir de la version Commentaires
email IR_WS_2.0
firstname IR_WS_2.0
gender IR_WS_2.0
lastname IR_WS_2.0
mobile IR_WS_2.0
phone IR_WS_2.0
title IR_WS_2.0
initials IR_WS_2.11
legalId IR_WS_2.17
positionOccupied IR_WS_2.17
workPhone IR_WS_2.21

Contenu de deliveryData

Champ A partir de la version Commentaires
deliveryChargeAmount IR_WS_2.6
estimatedDeliveryDate IR_WS_2.6
deliveryMode IR_WS_2.6
deliveryMethod IR_WS_2.6
deliveryOperator IR_WS_2.6
estimatedDeliveryDelay IR_WS_2.6
deliveryAddressCreationDate IR_WS_2.21
electronicDeliveryIndicator IR_WS_2.21
deliveryAddressStatus IR_WS_2.26

Contenu de fraudData

Champ A partir de la version Commentaires
bypassCtrlList IR_WS_2.0
bypassInfoList IR_WS_2.0
bypass3DS IR_WS_2.0
allowedCardCountryList IR_WS_2.0
deniedCardCountryList IR_WS_2.0
allowedIpCountryList IR_WS_2.0
deniedIpCountryList IR_WS_2.0
allowedCardArea IR_WS_2.0
deniedCardArea IR_WS_2.0
allowedIpArea IR_WS_2.0
deniedIpArea IR_WS_2.0
riskManagementDynamicSettingList IR_WS_2.0 Liste de conteneur riskManagementDynamicSetting. Voir la partie Containers
challengeMode3DS IR_WS_2.21
addressDeliveryBillingMatchIndicator IR_WS_2.21
nameDeliveryCustomerMatchIndicator IR_WS_2.21
reorderProductIndicator IR_WS_2.21
productAvailabilityIndicator IR_WS_2.21
merchantCustomerAuthentMethod IR_WS_2.23
merchantCustomerAuthentDateTime IR_WS_2.27
merchantCustomerAuthentData IR_WS_2.27
productAvailabilityDate IR_WS_2.27

Contenu de riskManagementDynamicSetting

Champ A partir de la version Commentaires
riskManagementDynamicParam IR_WS_2.0
riskManagementDynamicValue IR_WS_2.0

Contenu de holderAddress

Champ A partir de la version Commentaires
addressAdditional1 IR_WS_2.0
addressAdditional2 IR_WS_2.0
addressAdditional3 IR_WS_2.0
city IR_WS_2.0
company IR_WS_2.0
country IR_WS_2.0
postBox IR_WS_2.0
state IR_WS_2.0
street IR_WS_2.0
streetNumber IR_WS_2.0
zipCode IR_WS_2.0
businessName IR_WS_2.17

Contenu de holderContact

Champ A partir de la version Commentaires
email IR_WS_2.0
firstname IR_WS_2.0
gender IR_WS_2.0
lastname IR_WS_2.0
mobile IR_WS_2.0
phone IR_WS_2.0
title IR_WS_2.0
initials IR_WS_2.11
legalId IR_WS_2.17
positionOccupied IR_WS_2.17
workPhone IR_WS_2.21

Contenu de holderData

Champ A partir de la version Commentaires
birthCity IR_WS_2.6
birthCountry IR_WS_2.6
birthDate IR_WS_2.6
birthZipCode IR_WS_2.6
nationalityCountry IR_WS_2.6
newPassword IR_WS_2.6
password IR_WS_2.6
maidenName IR_WS_2.18

Contenu de instalmentData

Champ A partir de la version Commentaires
number IR_WS_2.0
datesList IR_WS_2.0
transactionReferencesList IR_WS_2.0
amountsList IR_WS_2.0
s10TransactionIdsList IR_WS_2.7

Contenu de orderContext

Champ A partir de la version Commentaires
customerHostName IR_WS_2.16
customerBrowserType IR_WS_2.16
customerANI IR_WS_2.16
customerANIInformationIdentifier IR_WS_2.16
merchantOrderSpecificDataList IR_WS_2.38 Liste de conteneur merchantOrderSpecificData. Voir la partie Containers

Contenu de merchantOrderSpecificData

Champ A partir de la version Commentaires
reference IR_WS_2.38
type IR_WS_2.38
value IR_WS_2.38

Contenu de travelContext

Champ A partir de la version Commentaires
departureDate IR_WS_2.16
passengerName IR_WS_2.16
originAirport IR_WS_2.16
numberOfRoutingCities IR_WS_2.16
routingCityList IR_WS_2.16
numberOfAirlineCarriers IR_WS_2.16
airlineCarrierList IR_WS_2.16
fareBasis IR_WS_2.16
numberOfPassengers IR_WS_2.16
destinationAirport IR_WS_2.16
reservationCode IR_WS_2.16

Contenu de paymentMeanData

Champ A partir de la version Commentaires
paypal IR_WS_2.0 Voir la partie Containers
sdd IR_WS_2.0 Voir la partie Containers
cofinoga3xcb IR_WS_2.0 Voir la partie Containers
passbe IR_WS_2.0 Voir la partie Containers
accord IR_WS_2.0 Voir la partie Containers
facilypay IR_WS_2.0 Voir la partie Containers
accordkdo IR_WS_2.0 Voir la partie Containers
presto IR_WS_2.0 Voir la partie Containers
cofidis3x IR_WS_2.0 Voir la partie Containers
unEuroCom IR_WS_2.0 Voir la partie Containers
cofidis4x IR_WS_2.0 Voir la partie Containers
cofinoga IR_WS_2.14 Voir la partie Containers
cetelem3x IR_WS_2.15 Voir la partie Containers
cetelem4x IR_WS_2.15 Voir la partie Containers
franfinance3xcb IR_WS_2.18 Voir la partie Containers
franfinance4xcb IR_WS_2.18 Voir la partie Containers
visaCheckout IR_WS_2.21 Voir la partie Containers
bcacb3X IR_WS_2.24 Voir la partie Containers
bcacb4X IR_WS_2.24 Voir la partie Containers
oney34x IR_WS_2.29 Voir la partie Containers

Contenu de paypal

Champ A partir de la version Commentaires
landingPage IR_WS_2.0
addrOverride IR_WS_2.0
invoiceId IR_WS_2.0
dupFlag IR_WS_2.0
dupDesc IR_WS_2.0
dupCustom IR_WS_2.0
dupType IR_WS_2.0
mobile IR_WS_2.0
orderDescription IR_WS_2.16

Contenu de sdd

Champ A partir de la version Commentaires
mandateAuthentMethod IR_WS_2.0
mandateUsage IR_WS_2.0
mandateCertificationType IR_WS_2.0

Contenu de cofinoga3xcb

Champ A partir de la version Commentaires
creditIndicator IR_WS_2.0

Contenu de passbe

Champ A partir de la version Commentaires
settlementModeList IR_WS_2.0

Contenu de accord

Champ A partir de la version Commentaires
settlementMode IR_WS_2.0
additionalAuthorisationNumber IR_WS_2.0

Contenu de facilypay

Champ A partir de la version Commentaires
settlementMode IR_WS_2.0
settlementModeVersion IR_WS_2.0
receiverType IR_WS_2.0
depositRefundIndicator IR_WS_2.0

Contenu de accordkdo

Champ A partir de la version Commentaires
additionalAuthorisationNumber IR_WS_2.0
blockAmountModification IR_WS_2.18

Contenu de presto

Champ A partir de la version Commentaires
paymentMeanCustomerId IR_WS_2.0
financialProduct IR_WS_2.0
prestoCardType IR_WS_2.0

Contenu de cofidis3x

Champ A partir de la version Commentaires
preScoreValue IR_WS_2.0
cofidisDisplayCancelButton IR_WS_2.0
cofidisPrivateData IR_WS_2.0
basket IR_WS_2.20

Contenu de unEuroCom

Champ A partir de la version Commentaires
preScoreValue IR_WS_2.0
cofidisPrivateData IR_WS_2.0
basket IR_WS_2.19

Contenu de cofidis4x

Champ A partir de la version Commentaires
preScoreValue IR_WS_2.0
cofidisDisplayCancelButton IR_WS_2.0
cofidisPrivateData IR_WS_2.0

Contenu de cofinoga

Champ A partir de la version Commentaires
paymentMeanTradeOptionList IR_WS_2.14 Liste de conteneur paymentMeanTradeOption. Voir la partie Containers

Contenu de paymentMeanTradeOption

Champ A partir de la version Commentaires
paymentMeanTradingName IR_WS_2.14
settlementModeList IR_WS_2.14

Contenu de cetelem3x

Champ A partir de la version Commentaires
cetelemPrivateMerchantData IR_WS_2.15
cetelemPrivateData IR_WS_2.15

Contenu de cetelem4x

Champ A partir de la version Commentaires
cetelemPrivateMerchantData IR_WS_2.15
cetelemPrivateData IR_WS_2.15

Contenu de franfinance3xcb

Champ A partir de la version Commentaires
authenticationKey IR_WS_2.18
pageCustomizationCode IR_WS_2.18
redirectionTimer IR_WS_2.18
testEnvironment IR_WS_2.18
birthPlaceCode IR_WS_2.18
conversionCurrency IR_WS_2.26
convertedAmount IR_WS_2.26

Contenu de franfinance4xcb

Champ A partir de la version Commentaires
authenticationKey IR_WS_2.18
pageCustomizationCode IR_WS_2.18
redirectionTimer IR_WS_2.18
testEnvironment IR_WS_2.18
birthPlaceCode IR_WS_2.18
conversionCurrency IR_WS_2.26
convertedAmount IR_WS_2.26

Contenu de visaCheckout

Champ A partir de la version Commentaires
visaCheckoutCallID IR_WS_2.21

Contenu de bcacb3X

Champ A partir de la version Commentaires
agencyCode IR_WS_2.24
challengeMode3DS IR_WS_2.24
numberOfCapturedTransaction IR_WS_2.24
numberOfRejectedTransaction IR_WS_2.24

Contenu de bcacb4X

Champ A partir de la version Commentaires
agencyCode IR_WS_2.24
challengeMode3DS IR_WS_2.24
numberOfCapturedTransaction IR_WS_2.24
numberOfRejectedTransaction IR_WS_2.24

Contenu de oney34x

Champ A partir de la version Commentaires
settlementMode IR_WS_2.29

Contenu de paypageData

Champ A partir de la version Commentaires
bypassReceiptPage IR_WS_2.11

Contenu de riskManagementCustomData

Champ A partir de la version Commentaires
riskManagementCustomSequence IR_WS_2.9
riskManagementCustomValue IR_WS_2.9

Contenu de s10TransactionReference

Champ A partir de la version Commentaires
s10TransactionId IR_WS_2.7
s10TransactionIdDate IR_WS_2.7 Ce champ est calculé par notre serveur. Il est donc inutile de le valoriser (il sera ignoré si valorisé)

Contenu de shoppingCartDetail

Champ A partir de la version Commentaires
shoppingCartTotalAmount IR_WS_2.6
shoppingCartTotalQuantity IR_WS_2.6
shoppingCartTotalTaxAmount IR_WS_2.6
mainProduct IR_WS_2.6
shoppingCartItemList IR_WS_2.6 Liste de conteneur shoppingCartItem. Voir la partie Containers
mainProductCategoryList IR_WS_2.24
discountAmount IR_WS_2.24
giftCardAmount IR_WS_2.27
giftCardCurrencyCode IR_WS_2.27
giftCardCount IR_WS_2.27

Contenu de shoppingCartItem

Champ A partir de la version Commentaires
productName IR_WS_2.6
productDescription IR_WS_2.6
productCode IR_WS_2.6
productSKU IR_WS_2.6
productUnitAmount IR_WS_2.6
productQuantity IR_WS_2.6
productTaxRate IR_WS_2.6
productUnitTaxAmount IR_WS_2.6
productCategory IR_WS_2.6
productTaxCategory IR_WS_2.6

Contenu de subMerchantAddress

Champ A partir de la version Commentaires
addressAdditional1 IR_WS_2.15
addressAdditional2 IR_WS_2.15
addressAdditional3 IR_WS_2.15
city IR_WS_2.15
company IR_WS_2.15
country IR_WS_2.15
postBox IR_WS_2.15
state IR_WS_2.15
street IR_WS_2.15
streetNumber IR_WS_2.15
zipCode IR_WS_2.15
businessName IR_WS_2.17

Voici un exemple de paramétrage de la requête de paiement pour chaque fonctionnalité disponible dans Sips Paypage SOAP (le détail de ces fonctionnalités est décrit dans le guide de configuration des fonctionnalités).

Il faut filtrer ceux qui s’afficheront dans la page de sélection des moyens de paiement grâce au champ paymentMeanBrandList :

..
        <urn:paymentMeanBrandList>
          <urn:paymentMeanBrand>VISA</urn:paymentMeanBrand>
          <urn:paymentMeanBrand>MASTERCARD</urn:paymentMeanBrand>
        </urn:paymentMeanBrandList>
..

La page de confirmation du paiement affichée par défaut par WL Sips peut être désactivée. Cette désactivation se fait par le champ paypageData.bypassReceiptPage :

..
          <urn:bypassReceiptPage>true</urn:bypassReceiptPage>
..

Pour choisir votre canal de paiement, vous devez remplir le champ orderChannel dans la requête de paiement :

..
        <urn:orderChannel>INTERNET</urn:orderChannel>
..

Dans le cas d’un paiement en fin de journée, il suffit de remplir les champs captureMode et captureDay :

..
        <urn:captureDay>0</urn:captureDay>
        <urn:captureMode>AUTHOR_CAPTURE</urn:captureMode>
..

Dans le cas d’un paiement à remiser N jours après l’acceptation en ligne, il suffit de remplir les champs captureMode et captureDay (3 jours dans notre exemple) :

..
        <urn:captureDay>3</urn:captureDay>
        <urn:captureMode>AUTHOR_CAPTURE</urn:captureMode>
..

Dans le cas d’un paiement à l’expédition, la transaction est envoyée en paiement lors votre validation, il faut juste remplir les champs captureMode et captureDay (3 jours de délai possible avant validation dans notre exemple) :

..
        <urn:captureDay>3</urn:captureDay>
        <urn:captureMode>VALIDATION</urn:captureMode>
..

Dans le cas d’un paiement en plusieurs échéances liées à une même transaction, il faut renseigner le champ paymentPattern à INSTALMENT et fournir le détail des échéances dans le champ instalmentData (600 € payés en 3 échéances dans notre exemple) :

..
        <urn:amount>60000</urn:amount>
..
        <urn:transactionReference>tref1</urn:transactionReference>
..
        <urn:instalmentData>
          <urn:number>3</urn:number>
          <urn:datesList>
            <urn:date>20170504</urn:date>
            <urn:date>20170604</urn:date>
            <urn:date>20170704</urn:date>
          </urn:datesList>
          <urn:transactionReferencesList>
            <urn:transactionReference>tref1</urn:transactionReference>
            <urn:transactionReference>tref2</urn:transactionReference>
            <urn:transactionReference>tref3</urn:transactionReference>
          </urn:transactionReferencesList>
          <urn:amountsList>
            <urn:amount>10000</urn:amount>
            <urn:amount>20000</urn:amount>
            <urn:amount>30000</urn:amount>
          </urn:amountsList>
        </urn:instalmentData>
..
        <urn:paymentPattern>INSTALMENT</urn:paymentPattern>
..

Si vous souhaitez un paiement immédiat (disponible uniquement pour certains moyens de paiement), la transaction est payée lors de l’autorisation en ligne :

..
        <urn:captureMode>IMMEDIATE</urn:captureMode>
..

Dans le cas des transactions multidevises le code devise doit être spécifié dans la requête. C’est dans le contrat d’acquisition où est précisée la devise de règlement.

..
        <urn:currencyCode>840</urn:currencyCode>
..

L’acceptation et le règlement sont effectués dans la même devise qui doit être spécifiée dans la requête. Le règlement en devises est une option du contrat d’acquisition.

..
        <urn:currencyCode>826</urn:currencyCode>
..

Pour désactiver dynamiquement l’authentification 3D Secure, il faut spécifier cette action dans le champ fraudData.bypass3DS :

..
        <urn:fraudData>
..
          <urn:bypass3DS>ALL</urn:bypass3DS>
..
        </urn:fraudData>
..

L'authentification forte, via le programme 3-D Secure par exemple, peut présenter un vrai avantage sur le parcours client lors de paiements de type OneClick. En effet, sur un paiement avec une authentification forte, il ne sera pas demandé au client de renseigner son cryptogramme visuel mais uniquement de sélectionner son moyen de paiement et de valider l'opération (fonctionnalité disponible pour les moyens de paiement des réseaux CB/VISA/MASTERCARD et sous réserve que votre acquéreur supporte cette fonctionnalité).

Il est néanmoins possible de désactiver dynamiquement l’authentification 3-D Secure pour les paiements OneClick.Il vous faudra spécifier cette action dans le champ fraudData.bypass3DS :

..
        <urn:fraudData>
..
          <urn:bypass3DS>MERCHANTWALLET</urn:bypass3DS>
..
        </urn:fraudData>
..

Pour un paiement Oneclick, l’identifiant du wallet du client doit être renseigné dans le champ merchantWalletId.

..
        <urn:merchantWalletId>1205987</urn:merchantWalletId>
..

Il faut 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 :

..
        <urn:intermediateServiceProviderId>241591</urn:intermediateServiceProviderId>
..

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

L’objectif principal de la réponse manuelle est de rediriger le client vers votre site Web avec le résultat du paiement pour que vous puissiez prendre la bonne décision le concernant. Par exemple, en cas d’erreur, vous pouvez suggérer de retenter le paiement. Dans le cas de paiement réussi, vous pouvez afficher un message de remerciement et commencer à expédier les marchandises.

À la dernière étape, un bouton « Continuer » est affiché sur la page de paiement chez WL Sips 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, tels que décrits ci-dessus. 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 êtes responsable d’afficher les messages pertinents (relatifs aux détails de la réponse) à votre client.

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 l’envoi 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.38. Veuillez consulter le dictionnaire de données pour une description complète des paramètres inclus dans la réponse.

La réponse automatique est envoyée seulement si le champ automaticResponseUrl a été envoyé dans la requête de paiement. 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 l’envoi 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.38. Veuillez consulter le dictionnaire de données pour une description complète des paramètres inclus dans la réponse.
Attention: la réponse automatique est systématique, asynchrone et renvoyée par le réseau ; elle est par définition dépendante des problèmes techniques potentiels des différents éléments de ce réseau et peut donc parfois être reçue avec un retard plus ou moins conséquent, voire même ne jamais être reçue.

La réponse automatique est transmise en fin de paiement. Toutefois, si votre client abandonne son achat, par exemple en quittant son navigateur, la réponse automatique est transmise lorsque la session utilisateur expire (au bout de 15 minutes d’inactivité). Par conséquent, si votre client abandonne son achat, vous recevrez uniquement la réponse automatique (pas la réponse manuelle), avec un code réponse renseigné à 97, environ 15 à 16 minutes après la redirection du client sur les pages de paiement.

Si une réponse automatique n’est pas reçue au bout de 16 minutes environ, vous pouvez obtenir le résultat d’un paiement en appelant la méthode getTransactionData de l’interface Sips Office, ou en analysant le contenu du journal des transactions. Vous pouvez également rechercher une transaction et voir son état en utilisant Sips Office Extranet.

Ci-dessous, vous trouverez 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 et si elles sont valides. Pour ce faire, vous pouvez tout simplement les copier et 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.
  • Il est impossible d’ajouter des paramètres de contexte aux adresses URL de réponse. Certains champs peuvent être néanmoins utilisés, par exemple, les champs orderID ou returnContext sont prévus pour les paramètres supplémentaires. Éventuellement, vous pouvez vous servir du champ sessionId pour retrouver les renseignements sur votre client à la fin du processus de paiement.

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.

Le contenu des réponses Sips Paypage automatiques et manuelles est identique. Le contenu peut varier en fonction du résultat (réussi ou autre).

Note: dans les réponses, en fonction de l’état de la transaction et du moyen de paiement choisi, certains champs peuvent être nuls, vides ou non renseignés. Veuillez consulter les documentations des moyens de paiement pour connaître les champs attendus dans les réponses.
Champ version Commentaires
acceptanceSystemApplicationId HP_2.18
acquirerContractNumber HP_2.25
acquirerNativeResponseCode HP_2.12
acquirerResponseCode HP_2.0
acquirerResponseIdentifier HP_2.8
acquirerResponseMessage HP_2.8
additionalAuthorisationNumber HP_2.8
amount HP_1.0 idem requête
authentExemptionReasonList HP_2.28
authorisationId HP_1.0
authorisationTypeLabel HP_2.18
authorMessageReference HP_2.18
avsAddressResponseCode HP_2.17
avsPostcodeResponseCode HP_2.17
captureDay HP_1.0 Champ de la requête qui peut être surchargé par WL Sips.
captureLimitDate HP_2.3
captureMode HP_1.0 Champ de la requête qui peut être surchargé par WL Sips.
cardCSCResultCode HP_2.0
cardProductCode HP_2.12
cardProductName HP_2.12
cardProductProfile HP_2.12
cardProductUsageLabel HP_2.18
complementaryCode HP_1.0
complementaryInfo HP_2.0
creditorId HP_2.7
currencyCode HP_1.0 idem requête
customerBusinessName HP_2.17
customerCompanyName HP_2.17
customerEmail HP_2.0 idem requête
customerId HP_2.0 idem requête
customerIpAddress HP_2.0 idem requête ou recalculé par Sips Paypage si absent
customerLegalId HP_2.17
customerMobilePhone HP_2.1 idem requête
customerPositionOccupied HP_2.17
dccAmount HP_2.3
dccCurrencyCode HP_2.3
dccExchangeRate HP_2.3
dccExchangeRateValidity HP_2.3
dccProvider HP_2.3
dccStatus HP_2.3
dccResponseCode HP_2.3
dueDate HP_2.3
guaranteeIndicator HP_2.0
hashPan1 HP_2.0
hashPan2 HP_2.0
holderAuthentMethod HP_2.4
holderAuthentProgram HP_2.5
holderAuthentRelegation HP_2.0
holderContactEmail HP_2.20
holderAuthentStatus HP_2.0
holderAuthentType HP_2.24
instalmentAmountsList HP_2.6
instalmentDatesList HP_2.6
instalmentNumber HP_2.6
instalmentTransactionReferencesList HP_2.6
interfaceVersion HP_1.0
intermediateServiceProviderOperationId HP_2.23
invoiceReference HP_2.10
issuerCode HP_2.12
issuerCountryCode HP_2.12
issuerEnrollementIndicator HP_2.0
issuerWalletInformation HP_2.9
keyVersion HP_1.0 idem requête
mandateAuthentMethod HP_2.2
mandateCertificationType HP_2.7
mandateId HP_2.3
mandateUsage HP_2.2
maskedPan HP_1.0
merchantId HP_1.0 idem requête
merchantSessionId HP_2.0 idem requête
merchantTransactionDateTime HP_2.0 idem requête
merchantWalletId HP_2.0 idem requête
orderChannel HP_2.0 idem requête
orderId HP_1.0 idem requête
panEntryMode HP_2.4
panExpiryDate HP_2.0
paymentAccountReference HP_2.28
paymentAttemptNumber HP_2.18
paymentMeanBrand HP_1.0
paymentMeanBrandSelectionStatus HP_2.14
paymentMeanData HP_2.2
paymentMeanId HP_2.6
paymentMeanTradingName HP_2.8
paymentMeanType HP_1.0
paymentPattern HP_2.0 idem requête
preAuthenticationColor HP_2.10
preAuthenticationInfo HP_2.10
preAuthenticationProfile HP_2.10
preAuthenticationProfileValue HP_2.14
preAuthenticationRuleResultList HP_2.14

Une liste d’objet preAuthenticationRuleResult.

Voir ci-dessous pour son contenu et son format.

preAuthenticationThreshold HP_2.10
preAuthenticationValue HP_2.10
preAuthorisationProfile HP_2.14
preAuthorisationProfileValue HP_2.14
preAuthorisationRuleResultList HP_2.14

Une liste d’objet preAuthenticationRuleResult.

Voir ci-dessous pour son contenu et son format.

responseCode HP_1.0
returnContext HP_1.0 idem requête
s10TransactionId HP_2.9
s10TransactionIdDate HP_2.9
s10transactionIdsList HP_2.11
schemeTransactionIdentifier HP_2.28
scoreColor HP_2.0
scoreInfo HP_2.0
scoreProfile HP_2.0
scoreThreshold HP_2.0
scoreValue HP_2.0
secureReference HP_2.26
settlementMode HP_2.7
settlementModeComplement HP_2.13
statementReference HP_2.4
tokenPan HP_2.0
transactionActors HP_2.2 idem requête
transactionDateTime HP_1.0
transactionOrigin HP_2.0 idem requête
transactionPlatform HP_2.16 systématiquement valorisé à ‘PROD’ pour le moment.
transactionReference HP_1.0
virtualCardIndicator HP_2.36
walletType HP_2.4
  • Contenu de preAuthenticationRuleResult
Champ Version Commentaires
ruleCode HP_2.14
ruleType HP_2.14
ruleWeight HP_2.14
ruleSetting HP_2.14
ruleResultIndicator HP_2.14
ruleDetailedInfo HP_2.14
  • Contenu de preAuthorisationRuleResult
Champ Version Commentaires
ruleCode HP_2.14
ruleType HP_2.14
ruleWeight HP_2.14
ruleSetting HP_2.14
ruleResultIndicator HP_2.14
ruleDetailedInfo HP_2.14

Le format d'une liste d'objets complexes dans les réponses automatiques et manuelles est défini comme suit (en gras) :

..|amount=1000|currencyCode=978|objectNameList=[{"field1":"value1a",
"field2":"value2a","field3":"value3a"…},{"field1":"value1b",
"field2":"value2b","field3":"value3b"}…]|transactionReference=1452687287828|..
  • le contenu de la liste est enveloppé dans une paire de crochets [ ] ;
  • chaque entrée de la liste est enveloppé dans une paire d'accolades { } ;
  • chaque champ est représenté comme "nomChamp" = "valeurChamp" ;
  • notez que le nom et la valeur du champ sont tous deux enveloppés dans une paire de doubles guillemets "" ;
  • les paires de nom/valeur adjacentes sont séparés par une virgule.

Exemple du champ preAuthorisationRuleResultList

Détail des règles fraude exécutées en préautorisation (en gras)

..|amount=1000|currencyCode=978|preAuthorisationRuleResultList=[
{”ruleCode”:"SC",”ruleType”:"NG",”ruleWeight”:"I",”ruleSetting”:"S",
”ruleResultIndicator”:"0",“ruleDetailedInfo”:"TRANS=1:5;
CUMUL=1000:99999900"},{”ruleCode”:"GC",”ruleType”:"NG",”ruleWeight”:
"D",”ruleSetting”:"N",”ruleResultIndicator”:"0",“ruleDetailedInfo”:
""},{”ruleCode”:"CR",”ruleType”:"NG",”ruleWeight”:"D",”ruleSetting”
:"S",”ruleResultIndicator”:"N",“ruleDetailedInfo”:"CARD_COUNTRY=USA"}]
|transactionReference=1452687287828|..

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 transaction est considéré comme inconnu : laissez la transaction en l’état, contactez le support et ne ré-exécutez pas la transaction de manière automatisée.

État Champs de la réponse Action à réaliser

Paiement accepté

responseCode = 00

acquirerResponseCode = 00

garanteeIndicator = Y,N,U, vide

Vous pouvez livrer la commande en fonction du niveau de garantie que vous souhaitez (champ garanteeIndicator).

Refus Fraude WL Sips Go-No-Go

responseCode = 05

complementaryCode = XX

preAuthorisationRuleResultList

Le paiement a été refusé par le moteur de fraude WL Sips que vous avez configuré.

Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par WL Sips pour connaître la cause du refus (champ preAuthorisationRuleResultList).

Refus Fraude WL Sips

Business Score

responseCode = 05

scoreColor = RED, BLACK

scoreValue = X (score de la transaction)

scoreThreshold = X,Y (seuil orange, seuil vert)

Le paiement a été refusé par le moteur de fraude WL Sips que vous avez configuré

Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par WL Sips pour connaître la cause du refus (champ preAuthorisationRuleResultList).

Warning Fraude WL Sips

Business Score

responseCode = 05

scoreColor = ORANGE

scoreValue = X (score de la transaction)

scoreThreshold = X,Y (seuil orange, seuil vert)

Le paiement a été autorisé par l’acquéreur mais le moteur de fraude WL Sips émet un warning par rapport aux règles que vous avez configurées.

Analysez le détail des règles fraudes exécutées par WL Sips pour connaître la cause du warning (champ preAuthorisationRuleResultList).

Si transaction non risquée alors acceptez-la avec la fonction acceptChallenge.

Si transaction risquée alors refusez-la avec la fonction refuseChallenge.

Les fonctions acceptChallenge et refuseChallenge sont disponibles sur le MEX et les connecteurs Sips Office et Sips Office Batch.

Refus 3-D Secure

reponseCode = 05

holderAuthenStatus = FAILURE

L’authentification du client a échoué, ce n’est pas nécessairement un cas de fraude. Vous pouvez proposer à votre client de payer avec un autre moyen de paiement en générant une nouvelle requête.

Refus bancaire acquéreur

responseCode = 05

acquirerResponseCode = XX

L’autorisation est refusée pour un motif non lié à la fraude.

Vous pouvez proposer à votre client de payer avec un autre moyen de paiement en générant une nouvelle requête.

Repli VADS

responseCode = 05

acquirerResponseCode = A1

Le paiement a été refusé par l'acquéreur car il manque les données 3-D Secure dans la demande d'autorisation.
Veuillez retenter le paiement avec une cinématique 3-D Secure.

Refus fraude acquéreur

responseCode = 34

acquirerResponseCode = XX

Autorisation refusée pour cause de fraude.

Ne livrez pas la commande.

Refus nombre max essais atteint

responseCode = 75

acquirerResponseCode = XX

L’acheteur a fait plusieurs tentatives toutes échouées car les informations saisies n’étaient pas correctes. Deux possibilités :

Difficulté pour votre client pour renseigner les informations cartes.

Tentative de carding (recherche de numéros de cartes possibles). Prenez contact avec votre client pour définir la suite à donner.

Refus suite problème technique

responseCode = 90, 99

acquirerResponseCode = 90 à 98

Problème technique temporaire lors du traitement de la transaction.

Proposez à votre client de refaire un paiement ultérieurement.

Abandon du paiement responseCode = 97

acquirerResponseCode = non renseigné

Ne livrez pas la commande

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

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

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
Clé secrète (secretKey) 002001000000001_KEY1
Version de la clé (keyVersion) 1
Table 2. transactionReference généré par WL Sips
Champ Valeur
ID du commerçant (merchantId) 002001000000002
Clé secrète (secretKey) 002001000000002_KEY1
Version de la clé (keyVersion) 1
Table 3. transactionId généré par le commerçant
Champ Valeur
ID du commerçant (merchantId) 002001000000003
Clé secrète (secretKey) 002001000000003_KEY1
Version de la clé (keyVersion) 1
Table 4. transactionId généré par WL Sips
Champ Valeur
ID du commerçant (merchantId) 002001000000004
Clé secrète (secretKey) 002001000000004_KEY1
Version de la clé (keyVersion) 1

Ce serveur de simulation n’est pas raccordé aux serveurs bancaires réels car sa fonction est de valider la connexion entre votre site Web et le serveur de paiement.

Sips Paypage simule donc l’appel aux serveurs d’autorisation pour vous permettre de tester les différents résultats d’un paiement.

Il n’est donc pas nécessaire d’utiliser des cartes réelles pour effectuer les tests.

Attention: puisque le merchantId est partagé entre tous les commerçants/prospects, il existe un risque de doublon de transactionReference. Par conséquent, il est vivement recommandé que tous les transactionReference soient préfixés par le nom de la future boutique qui sera utilisée dans l’environnement de production. Cela facilite aussi le support en cas d’appel à l’assistance technique.

Vous utilisez une boutique générique sans personnalisation de la page de paiement. C’est lors de l’étape 4 que vous pouvez personnaliser vos pages de paiements.

Les règles de simulation suivantes s’appliquent :

  • le numéro de carte (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
    MAESTRO 500000
    MASTERCARD 510000
    Cartes co-badgées CB et MASTERCARD 520000
    Cartes co-badgées CB et MAESTRO 530000
  • le code réponse WL Sips (champ responseCode) est calculé à partir des deux derniers chiffres du numéro de carte ;
  • le code de sécurité (CVV) comporte 3 ou 4 chiffres. Cette valeur est sans importance pour le résultat de la simulation.

Exemple : si vous utilisez le numéro de carte 4100 0000 0000 0005, la carte sera identifiée comme VISA et le paiement sera refusé (code réponse WL Sips 05).

Note: si le code réponse WL Sips calculé n’est pas référencé, la transaction est acceptée (respondeCode = 00).

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

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.

Si vous choisissez de tester iDeal, vous serez redirigé vers le serveur de simulation qui simule les transactions iDeal selon leur montant. Ensuite, vous retournerez au serveur de paiement qui affiche le ticket avec le résultat de la transaction.

Règles de simulation d’un paiement iDeal :

Montant de la transaction Réponse de iDeal
2,00 EUR Transaction annulée
3,00 EUR Transaction expirée
4,00 EUR Transaction non réalisée
5,00 EUR Échec de la transaction
Autres cas Transaction OK

Si vous choisissez de tester PayPal, vous êtes redirigé vers le serveur de simulation qui simule les transactions PayPal selon leur résultat du paiement chez PayPal. Ensuite, vous retournez au serveur de paiement qui affiche le ticket avec le résultat du paiement.

Une fois la connexion de votre site Web à Sips Paypage SOAP testée, vous êtes à présent en mesure de valider la connexion à Sips Paypage 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-services.com/services/v2/paymentInit
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.

Immédiatement :

  • faites une transaction avec une carte de paiement réelle (si possible la vôtre). Si la transaction est acceptée, elle sera envoyée en banque pour créditer votre compte commerçant et débiter le compte carte ;
  • vérifiez que vos pages de paiement intègrent vos paramètres de personnalisation ;
  • consultez la transaction via Sips Office Extranet à partir du transactionReference.

Le lendemain :

  • vérifiez la présence de la transaction dans le journal des transactions ;
  • vérifiez sur votre compte que l’opération a bien été créditée ;
  • remboursez la transaction via Sips Office Extranet (optionnel).

Le surlendemain :

  • vérifiez que l’opération de remboursement apparaît dans le journal des opérations ;
  • vérifiez sur votre compte le débit suite au remboursement.

Cette procédure de validation est également applicable au moyen de paiement PayPal.

Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’acheter et de payer.

Dans la journée :

  • surveillez le taux d’acceptation (nombre de responseCode 00 / nombre total de transactions).
  • vérifiez la nature des refus non bancaires :
    • problème technique : responseCode 90, 99,
    • fraude : responseCode 34,
    • nombre max de tentatives de paiement atteint : responseCode 75,
    • abandon : responseCode 97.

Le lendemain :

  • vérifiez dans le journal des transactions la présence de toutes les transactions traitées (acceptées et refusées) ;
  • vérifiez, dans le journal des opérations, les opérations que vous avez effectuées ainsi que les remises (si vous avez choisi cette option du journal).

Ce site utilise des cookies 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 cookies sur votre appareil.

Paramètres