WL SIPS DOCS

Release 24.6

aller directement au contenu

Rechercher par mots clés

Sips In-App JSON

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

La dernière interfaceVersion est 3.0.

Avant de lire ce document nous vous conseillons

Worldline 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 jusqu’au démarrage en production.

Ce document s’adresse aux commerçants qui souhaitent souscrire à l’offre Worldline Sips et proposer le paiement intégré à leur application mobile. Le connecteur In-App est basé sur des échanges JSON via le protocole REST, en mode machine à machine.

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

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

Une connaissance des standards relatifs aux langages de programmation Web pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour pouvoir développer un client capable de se connecter à la passerelle Sips In-App.

De plus, une connaissance des standards relatifs aux langages de programmation Mobile pratiqués aujourd'hui est nécessaire pour intégrer les SDK Sips In-App à vos applications mobile pour Android et iOS.

Remarque : Des documents dédiés sont disponibles pour intégrer le SDK Sips In-App pour Android et pour iOS.
Remarque : 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 Merchant Extranet (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 Worldline 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 Merchant Extranet (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).

Worldline a supprimé la contrainte PCI-DSS de votre côté car des données carte chiffrées transitent entre les applications mobiles et le serveur Worldline Sips.

En effet, les données carte ne transitent jamais par votre serveur et cela ne doit jamais être le cas.

Par conséquent, votre application n'a pas à se conformer à la norme PCI-DSS ; elle doit simplement respecter les pratiques d'excellence PCI-DSS décrites à cette adresse : https://www.pcisecuritystandards.org/document_library?association=PA-DSS

Le principe général du fonctionnement de Sips In-App est le suivant :


image describing the general principle of operation of the connector

1) Le client déclenche une action sur l'application mobile commerçant nécessitant une cinématique In-App. 2) Votre serveur effectue une requête d'initialisation auprès du serveur In-App. 3) Le serveur In-App renvoie les données nécessaires au bon fonctionnement du SDK in-App, dont la clé publique. 4) Votre serveur renvoie les données récupérées à l'étape précédente vers l'application mobile. 5) Via le SDK In-App, votre application mobile requête le serveur In-App pour effectuer les actions souhaitées en transitant les éventuelles données sensibles chiffrées. 6) Le serveur In-App retourne la réponse à votre requête à votre application mobile via le SDK In-App. 7) Le serveur In-App envoie la réponse à votre serveur (option). 8) Votre application mobile retourne le résultat du traitement à votre serveur.

Remarque : Il existe plusieurs cinématiques possibles dont certaines demanderont plusieurs interactions entre votre application mobile et le serveur In-App, ou avec des systèmes externes (exemple : redirection vers l'ACS pour une authentification 3-D Secure). Les différentes cinématiques sont décrites plus loin.
Attention : il vous appartient d'éviter les attaques de « l'homme du milieu » (en anglais : « man-in-the-middle ») entre les flux 1 et 4 (plus d'informations sur https://fr.wikipedia.org/wiki/Attaque_de_l'homme_du_milieu).

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 Merchant Extranet (récupération de la clé secrète et gestion de caisse).

Remarque : Pour Merchant Extranet, les informations de connexion sont envoyées au contact administratif.

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.

Comme indiqué précédemment, la première étape d'une cinématique Sips In-App est d'initialiser cette cinématique. Cette initialisation se traduit par un appel vers un service Web REST (JSON) situé sur la plateforme de paiement Worldline Sips.

Une requête est composée de champs génériques et de champs de type container.

Un container est une structure utilisée afin de regrouper fonctionnellement les données.

Si le champ est de type container, cette précision est indiquée dans la colonne commentaire qui renvoie à la partie dédiée détaillant le contenu de tous les champs de ce type.

Tous les champs nécessaires pour chaque requête doivent être fournis.

Attention : pour rappel, il est nécessaire d'indiquer, dans l'en-tête de votre message, que les données à traiter sont de type JSON. Vous devez pour cela préciser l'en-tête 'Content-Type: application/json' dans votre message JSON. À défaut vous risquez de recevoir un message d'erreur de ce type :
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html>
    <head>
        <title>415 Unsupported Media Type</title>
    </head>
    <body>
        <h1>Unsupported Media Type</h1>
        <p>The supplied request data is not in a format acceptable for processing by this resource.</p>
    </body>
</html>
Remarque : dans les réponses, en fonction du résultat de la demande, certains champs peuvent être nuls, vides ou non renseignés.

La requête est construite conformément au format JSON :

{“<nom du champ>” : ”<nom de la valeur>”, “<nom du champ>” : “<nom de la valeur>”, “nom du champ” : “Nom de la valeur” etc., “seal” : “valeur de seal”}

Exemple d’une requête de paiement d’un montant de 10 euros :

{"amount" : "1000","currencyCode" : "978","interfaceVersion" : "IR_MB_2.38","keyVersion" : 
"1","merchantId" : "012345678911111","paymentMeanBrand" : "VISA","paymentPattern" : 
"ONE_SHOT","sdkOperationName" : "CARDORDER","transactionReference" : "STHTSH4418152014","seal" : 
"05f6b5cc0b2a31eb3a976f060a3824874cc7bf01c081f17956f125f586eb27ba"}

La syntaxe utilisée pour créer une liste en JSON suit la norme. Voici un résumé de cette structure pour les deux principaux types de listes : les listes de champs simples (par ex. chaînes de caractères) et les listes d’objets.

Il est possible d’avoir une liste de valeurs pour un même champ :

…,"nom du champ" : ["valeur1","valeur2"],…

Exemple avec le champ paymentMeanBrandList valorisé avec VISA et MASTERCARD :

…,"paymentMeanBrandList" : ["VISA","MASTERCARD"],…

Si un champ contient une liste d’objets complexes, sa représentation est construite conformément au format suivant :

…,“nom du champ” : [{“nom du sous-champ1”:”valeur1”,“nom du sous-champ2”:”valeur2”},{“nom du souschamp1”:”valeur3”, “nom du sous-champ2”:”valeur4”}],…

Exemple d’une requête de paiement avec une liste d’objets complexes pour le champ shoppingCartDetail contenant deux produits nommés apple et mango :

{"amount" : "1000","currencyCode" : "978","interfaceVersion" : "IR_MB_2.38","keyVersion" : 
"1","merchantId" : "012345678911111","paymentMeanBrand" : "VISA","paymentPattern" : 
"ONE_SHOT","sdkOperationName" : "CARDORDER","shoppingCartDetail" : {"shoppingCartItemList" : [{"productCode" : 
"123","productName" : "apple"},{"productCode" : "456","productName" : "mango"}],"shoppingCartTotalAmount" : 
"1000"},"transactionReference" : "6549854FCEX12867","seal" : 
"17cb94b79102b492eccd335cb8e5633e243f12ce116a496b45c93d7b6908bb0b"}

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. Worldline 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 :

{
  "amount" : "2500",
  "automaticResponseUrl" : "https://automatic-response-url.fr/",
  "captureDay" : "0",
  "captureMode" : "AUTHOR_CAPTURE",
  "currencyCode" : "978",
  "interfaceVersion" : "IR_MB_2.38",
  "keyVersion" : "1",
  "merchantId" : "011223344550000",
  "sdkOperationName" : "CARDORDER",
  "sdkVersion" : "SDK100",
  "transactionReference" : "TREFEXA2021",
  "seal" : "c4372c03a0d678fcf5a401d6a7d8625785580d07257208b8c0dc098e0109963a"
}

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_CAPTURE978IR_MB_2.38011223344550000CARDORDERSDK100TREFEXA2021

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

secret123

Le seal attendu est :

c4372c03a0d678fcf5a401d6a7d8625785580d07257208b8c0dc098e0109963a

Avec le connecteur Sips In-App, vous pouvez effectuer plusieurs types de cinématiques de paiement selon le champ sdkOperationName renseigné en requête de l'opération orderInitialize :

  • Cinématique de paiement carte sans authentification porteur (sdkOperationName=CARDORDER)
  • Cinématique de paiement carte avec authentification porteur (sdkOperationName=THREEDSECUREANDORDER)
  • Cinématique de paiement par Wallet sans authentification porteur (sdkOperationName=WALLETORDER)
  • Cinématique de paiement par Wallet avec authentification porteur (sdkOperationName=THREEDSECUREANDWALLETORDER)
  • Cinématique de paiement déportée sur un fournisseur de moyen de paiement (sdkOperationName=PAYMENTPROVIDERORDER)

Ces différentes cinématiques sont décrites ci-après.

Une cinématique de paiement carte sans authentification porteur via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de paiement auprès du serveur Worldline Sips via le service orderInitialize (avec sdkOperationName=CARDORDER) ;
  • Une fois les informations carte saisies par le porteur, effectuer le paiement en appelant le service cardOrder depuis l'application mobile via le SDK Sips In-App.

image trop complexe pour être décrite, merci de prendre contact avec le support

Une cinématique de paiement carte avec authentification porteur via Sips In-App se déroule en 4 étapes :

  • Initialiser la cinématique de paiement auprès du serveur Worldline Sips via le service orderInitialize (avec sdkOperationName=THREEDSECUREANDORDER) ;
  • Une fois les informations carte saisies par le porteur, effectuer une demande de vérification de l'enrôlement du porteur en appelant le service cardCheckEnrollment depuis l'application mobile via le SDK Sips In-App ;
  • Rediriger le porteur vers l'ACS pour authentification ;
  • Effectuer le paiement en appelant le service cardValidateAuthenticationAndOrder depuis l'application mobile via le SDK Sips In-App.

image trop complexe pour être décrite, merci de prendre contact avec le support

Une cinématique de paiement par Wallet client sans authentification porteur via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de paiement auprès du serveur Worldline Sips via le service orderInitialize (avec sdkOperationName=WALLETORDER) ;
  • Une fois le moyen de paiement choisi par le porteur, effectuer le paiement en appelant le service walletOrder depuis l'application mobile via le SDK Sips In-App.

image too complex to be described, please contact the support

Une cinématique de paiement par Wallet client avec authentification porteur via Sips In-App se déroule en 4 étapes :

  • Initialiser la cinématique de paiement auprès du serveur Worldline Sips via le service orderInitialize (avec sdkOperationName=THREEDSECUREANDWALLETORDER) ;
  • Une fois le moyen de paiement choisi par le porteur, effectuer une demande de vérification de l'enrôlement du porteur en appelant le service walletCheckEnrollment depuis l'application mobile via le SDK Sips In-App ;
  • Rediriger le porteur vers l'ACS pour authentification ;
  • Effectuer le paiement en appelant le service cardValidateAuthenticationAndOrder depuis l'application mobile via le SDK Sips In-App.

image trop complexe pour être décrite, merci de prendre contact avec le support

Une cinématique de paiement avec moyen de paiement déporté via Sips In-App se déroule en 4 étapes :

  • Initialiser la cinématique de paiement auprès du serveur Worldline Sips via le service orderInitialize (avec sdkOperationName=PAYMENTPROVIDERORDER) ;
  • Effectuer un appel au service paymentProviderOrder depuis l'application mobile via le SDK Sips In-App pour lancer le paiement et récupérer l'URL-intent permettant de déclencher l'ouverture de l'application mobile du moyen de paiement déporté ;
  • Rediriger le porteur sur l'application mobile du moyen de paiement déporté ;
  • Une fois le porteur de retour sur l'application mobile commerçant, effectuer un appel au service getTransactionData depuis l'application mobile via le SDK Sips In-App pour connaitre le statut de la transaction (paiement réussi ou échoué).
Remarque : Cette cinématique est disponible pour le moyen de paiement BCMC Mobile uniquement.

image trop complexe pour être décrite, merci de prendre contact avec le support

La requête et la réponse de la fonction orderInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par Sips In-App à 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'appel, par votre application mobile, du service souhaité (cardOrder, cardCheckEnrollment, walletOrder, walletCheckEnrollment ou paymentProviderOrder).
03 L’identifiant commerçant ou le contrat acquéreur sont incorrects.
12 Les paramètres de la transaction sont incorrects. Vérifiez les paramètres de la requête (l'erreur est indiquée dans le redirectionStatusMessage).
30 Le format de la requête est incorrect (l'erreur est indiquée dans le redirectionStatusMessage).
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 par l'appel, par votre application mobile, du service souhaité (cardOrder, cardCheckEnrollment, walletOrder, walletCheckEnrollment ou paymentProviderOrder).

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

En fin de cinématique de paiement, en plus de la réponse fournie par le serveur Worldline Sips à votre application mobile via le SDK Sips In-App, vous avez également la possibilité de recevoir une réponse directement sur votre serveur. Cette réponse automatique est une réponse HTTP(S) POST envoyée sur l'URL automaticResponseUrl précisée optionnellement dans la requête.

Vous devez mettre en place le système permettant de décoder cette réponse, afin de connaître le résultat du paiement.

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
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) de la réponse 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.

Remarque : 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 "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) )

La réponse automatique est envoyée seulement si le champ automaticResponseUrl a été envoyé dans la requête d'initialisation d'une cinématique de paiement. Si tel est le cas, le serveur Worldline Sips envoie une réponse HTTP(S) POST à l’adresse URL reçue.

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.

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. Si une réponse automatique n’est pas reçue, 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.
Choisir le format de la réponse : POST ou JSON

A partir de l'interfaceVersion HP_3.0 Sips vous envoie la chaîne concaténée de la réponse (champ Data) sous 2 formats au choix :

Le format POST

Ce format POST a la structure suivante : clé1=valeur1|clé2=valeur2…

Exemple d'une réponse en POST avec séparateur "pipe" entre les données

captureDay=0|captureMode=AUTHOR_CAPTURE|currencyCode=978|merchantId=039000254447216
    |orderChannel=INTERNET|responseCode=00|transactionDateTime=2022-11-14T11:21:12+01:00|transactionReference=SIM20221114112037
    |keyVersion=1|acquirerResponseCode=00|amount=1000|authorisationId=664865|guaranteeIndicator=N|panExpiryDate=202401
    |paymentMeanBrand=VISA|paymentMeanType=CARD|customerIpAddress=10.78.106.18|maskedPan=############0600|holderAuthentRelegation=N
    |holderAuthentStatus=NOT_PARTICIPATING|tokenPan=490700h719850600|transactionOrigin=SIMS|paymentPattern=ONE_SHOT
    |customerMobilePhone=null|mandateAuthentMethod=null|mandateUsage=null|transactionActors=null|mandateId=null|captureLimitDate=20221114
    |dccStatus=null|dccResponseCode=null|dccAmount=null|dccCurrencyCode=null|dccExchangeRate=null|dccExchangeRateValidity=null
    |dccProvider=null|statementReference=null|panEntryMode=MANUAL|walletType=null|holderAuthentMethod=NO_AUTHENT_METHOD
    |holderAuthentProgram=3DS_V2|paymentMeanId=null|instalmentNumber=null|instalmentDatesList=null|instalmentTransactionReferencesList=null
    |instalmentAmountsList=null|settlementMode=null|mandateCertificationType=null|valueDate=null|creditorId=null
    |acquirerResponseIdentifier=null|acquirerResponseMessage=null|paymentMeanTradingName=null|additionalAuthorisationNumber=null
    |issuerWalletInformation=null|s10TransactionId=6|s10TransactionIdDate=20221114|preAuthenticationColor=null|preAuthenticationInfo=null
    |preAuthenticationProfile=null|preAuthenticationThreshold=null|preAuthenticationValue=null|invoiceReference=null|s10transactionIdsList=null
    |cardProductCode=F|cardProductName=VISA CLASSIC|cardProductProfile=C|issuerCode=00000|issuerCountryCode=GRC|acquirerNativeResponseCode=00
    |settlementModeComplement=null|preAuthorisationProfile=null|preAuthorisationProfileValue=null
    |preAuthorisationRuleResultList=[{"ruleCode":"VI","ruleType":"NG","ruleWeight":"I","ruleSetting":"S","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:3;CUMUL=24999:200000"},{"ruleCode":"RCode","ruleType":"RType","ruleWeight":"RWeight","ruleSetting":"RSetting","ruleResultIndicator":"RIndicator","ruleDetailedInfo":"DetailedInfo"}]
    |preAuthenticationProfileValue=null|preAuthenticationRuleResultList=null|paymentMeanBrandSelectionStatus=NOT_APPLICABLE|transactionPlatform=PROD
    |avsAddressResponseCode=null|avsPostcodeResponseCode=null|customerCompanyName=null|customerBusinessName=null|customerLegalId=null
    |customerPositionOccupied=null|paymentAttemptNumber=1|holderContactEmail=null|installmentIntermediateServiceProviderOperationIdsList=null
    |holderAuthentType=null|acquirerContractNumber=3863090010|secureReference=null|authentExemptionReasonList=null
    |paymentAccountReference=a667b63d8bec4fb980106497c53e4|schemeTransactionIdentifier=b4e683c1a6ff4a09a0415116a0a25b401d38c19d24e643078d
    |guaranteeLimitDateTime=null|paymentMeanDataProvider=null|virtualCardIndicator=N|cardProductUsageLabel=CREDIT|authorisationTypeLabel=TRANSACTION DE PAIEMENT
    |authorMessageReference=272612|acceptanceSystemApplicationId=142000000001|challengeMode3DS=null|issuingCountryCode=GRC|abortedProcessingStep=null|abortedProcessingLocation=null

Le format JSON

Le format JSON a la structure suivante : { "clé1" : "valeur1", "clé2" : "valeur2", …}

Remarque : Le format JSON affiche aisément une liste ou une collection d’objets avec la structure suivante : "listeClient" : [ { "nom" : "nom1", "prenom" : "prenom1",… }, { "nom" : "nom2", "prenom" : "prenom2",… } ]

Exemple d'une réponse en JSON


    {
  		"keyVersion": 1, "acquirerResponseCode": "00", "acquirerResponseDescription": "Transaction approved or processed successfully",
  		"amount": 1000, "authorisationId": "858191", "captureDay": 0, "captureMode": "AUTHOR_CAPTURE", "cardScheme": "VISA",
  		"chargeAmount": 0, "currencyCode": "978", "customerIpAddress": "10.78.106.18", "guaranteeIndicator": "N",
  		"holderAuthentRelegation": "N", "holderAuthentStatus": "NOT_PARTICIPATING", "maskedPan": "############0600",
  		"merchantId": "039000254447216", "orderAmount": 1000, "orderChannel": "INTERNET", "panExpiryDate": "202401",
  		"paymentMeanBrand": "VISA", "paymentPattern": "ONE_SHOT", "responseCode": "00", "responseDescription": "Process succeeded",
  		"tokenPan": "490700h719850600", "transactionDateTime": "2022-11-14.11:19:39+0100", "transactionOrigin": "SIMS",
  		"transactionReference": "SIM20221114111757", "captureLimitDate": "20221114", "paymentMeanType": "CARD", "panEntryMode": "MANUAL",
  		"holderAuthentMethod": "NO_AUTHENT_METHOD", "holderAuthentProgram": "3DS_V2", "s10TransactionId": "5", "s10TransactionIdDate": "20221114",
  		"cardProductCode": "F", "cardProductName": "VISA CLASSIC", "cardProductProfile": "C", "issuerCode": "00000", "issuerCountryCode": "GRC",
  		"acquirerNativeResponseCode": "00", "sealAlgorithm": "sha256", "paymentMeanBrandSelectionStatus": "NOT_APPLICABLE",
  		"transactionPlatform": "PROD", "paymentAttemptNumber": 1, "acquirerContractNumber": "3863090010",
  		"schemeTransactionIdentifier": "79e70b862e5942ff86f31951235959a16f45f41f797f48129e",
  		"paymentAccountReference": "945dbb3e0b984bfc896a04c5bc273", "virtualCardIndicator": "N", "cardProductUsageLabel": "CREDIT",
  		"authorisationTypeLabel": "TRANSACTION DE PAIEMENT", "authorMessageReference": "179263", "acceptanceSystemApplicationId": "142000000001",
  		"issuingCountryCode": "GRC", "threeDLiabilityShift": "N", "threeDStatusCode": "NOT_PARTICIPATING", "threeDRelegationCode": "N",
  		"preAuthorisationRuleResultList":[
  		    {"ruleCode":"VI","ruleType":"NG","ruleWeight":"I","ruleSetting":"S","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:3;CUMUL=24999:200000"},
  		    {"ruleCode":"RCode","ruleType":"RType","ruleWeight":"RWeight","ruleSetting":"RSetting","ruleResultIndicator":"RIndicator","ruleDetailedInfo":"DetailedInfo"}
  		]
	}
    

Comportement par défaut à partir de l'interfaceVersion HP_3.0

Le format de la réponse automatique est déterminé par le connecteur qui a été utilisé lors des échanges HTTPS entre votre site Web et les serveurs de paiement Sips.

Conseil : Voici un tableau récapitulatif du fonctionnement entre InterfaceVersion IR_MB_3.x / Connecteur appelé / Format des réponses
Interface Version Connecteur Format des réponses
IR_MB_3.x JSON JSON (JS_3.x)

Choisir les versions des réponses depuis la requête de paiement

Si vous souhaitez contourner ce comportement par défaut il est possible de renseigner depuis la requête de paiement la version exacte de réponse automatique que vous utilisez.

Le champs de la requête de paiement qui permet de renseigner la version de la réponse automatique est interfaceVersionAutomaticResponse

Attention : Si la version interfaceVersionAutomaticResponse renseignée dans la requête est incorrecte alors la requête d'initialisation de paiement est en echec (code erreur 30).

Ci-dessous, vous trouverez une liste des problèmes les plus couramment observés qui bloquent la réception de la réponse automatique. Assurez-vous de les avoir vérifiés avant d’appeler le service d’assistance technique.

  • Vérifiez si l'adresse URL de réponse automatique est fournie dans la requête et si elle est valide. Pour ce faire, vous pouvez tout simplement la copier et coller dans votre navigateur.
  • L'adresse URL fournie doit être accessible 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 à l'adresse URL de réponse automatique 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 Worldline Sips.
  • Il est impossible d’ajouter des paramètres de contexte à l'adresse URL de réponse automatique. 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 Worldline 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 Worldline Sips. Pour ces raisons, le serveur de paiement envoie une réponse sans signature dans le champ Seal.

Le contenu de la réponse automatique peut varier en fonction du résultat (réussi ou autre), du moyen de paiement ou de la configuration de votre boutique.

Remarque : 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.

Contenu de la réponse automatique :

Champ version Commentaires
acceptanceSystemApplicationId HP_2.39
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.39
authorMessageReference HP_2.39
avsAddressResponseCode HP_2.17
avsPostcodeResponseCode HP_2.17
captureDay HP_1.0 Champ de la requête qui peut être surchargé par Worldline Sips.
captureLimitDate HP_2.3
captureMode HP_1.0 Champ de la requête qui peut être surchargé par Worldline Sips.
cardCSCResultCode HP_2.0
cardProductCode HP_2.12
cardProductName HP_2.12
cardProductProfile HP_2.12
cardProductUsageLabel HP_2.39
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
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
issuingCountryCode HP_2.44
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

Liste de Contenu d'un ruleResult.

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

Liste de Contenu d'un ruleResult.

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 d'un ruleResult :

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 la réponse automatique est défini comme suit :

...|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 avec le champ preAuthorisationRuleResultList :

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

Une fois la cinématique de paiement terminée, vous devez analyser la réponse reçue pour connaitre le résultat. Cette réponse est fournie à l'application mobile en retour de l'appel à la fonction de paiement, ainsi que via l'URL de réponse automatique si vous avez renseigné celle-ci en requête d'initialisation.

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.

Attention : 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 Worldline Sips
Go-No-Go
responseCode = 05
complementaryCode = XX
preAuthorisationRuleResultList
Le paiement a été refusé par le moteur de fraude Worldline Sips que vous avez configuré.
Ne livrez pas la marchandise.
Analysez le détail des règles fraudes exécutées par Worldline Sips pour connaître la cause du refus (champ preAuthorisationRuleResultList).
Refus Fraude Worldline 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 Worldline Sips que vous avez configuré.
Ne livrez pas la marchandise.
Analysez le détail des règles fraudes exécutées par Worldline Sips pour connaître la cause du refus (champ preAuthorisationRuleResultList).
Warning Fraude Worldline 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 Worldline 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 Worldline Sips pour connaître la cause du warning (champ preAuthorisationRuleResultList).
  • Si la transaction est non risquée, alors acceptez-la avec la fonction acceptChallenge.
  • Si la transaction est risquée, alors refusez-la avec la fonction refuseChallenge.
Les fonctions acceptChallenge et refuseChallenge sont disponibles sur l’extranet et les connecteurs Sips Office.
Refus 3D Secure
responseCode = 05
holderAuthenStatus = FAILURE
L’authentification de l’acheteur a échoué, ce n’est pas nécessairement un cas de fraude.
Vous pouvez proposer à votre client de payer avec 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 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.

Avec le connecteur Sips In-App, vous pouvez effectuer une cinématique de génération de Token de paiement via l'opération paymentTokenInitialize, avec le champ sdkOperationName renseigné à PAYMENTTOKENGENERATE.

Le principe de cette cinématique est d'envoyer les données carte saisies par le client sur votre application mobile, directement depuis le mobile du client vers le serveur Sips In-App, et de récupérer en réponse un Token de paiement, nommé paymentToken, vous permettant de déclencher la suite de la cinématique depuis votre serveur, sans données sensibles. Cela peut vous permettre notamment de mutualiser vos cinématiques de paiement In-App et Web si vous utilisez le connecteur Sips Hosted Fields pour les paiements Web.

Une cinématique de génération de Token de paiement via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de génération de Token de paiement auprès du serveur Worldline Sips via le service paymentTokenInitialize (avec sdkOperationName=PAYMENTTOKENGENERATE) ;
  • Une fois les informations carte saisies par le porteur, effectuer une demande de génération de Token de paiement en appelant le service paymentTokenGenerate depuis l'application mobile via le SDK Sips In-App.

Le paymentToken reçu en réponse vous permet d'effectuer la suite de la cinématique souhaitée directement depuis votre serveur sans transiter de données sensibles.


image trop complexe pour être décrite, merci de prendre contact avec le support

La requête et la réponse de la fonction paymentTokenInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par Sips In-App à 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'appel, par votre application mobile, du service paymentTokenGenerate.
03 L’identifiant commerçant ou le contrat acquéreur sont incorrects.
12 Les paramètres de la transaction sont incorrects. Vérifiez les paramètres de la requête (l'erreur est indiquée dans le redirectionStatusMessage).
30 Le format de la requête est incorrect (l'erreur est indiquée dans le redirectionStatusMessage).
34 Problème de sécurité : par ex. le sceau calculé est incorrect.
40 Fonction non gérée.
99 Service temporairement indisponible.

3 cas sont possibles :

  • redirectionStatusCode = 00

Ce cas doit être suivi par l'appel, par votre application mobile, du service paymentTokenGenerate.

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

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 = 99

Problème de disponibilité du service. Vous devez essayer de renvoyer la requête.

Avec le connecteur Sips In-App, vous pouvez effectuer plusieurs types de cinématiques de gestion du Wallet selon le champ sdkOperationName renseigné en requête de l'opération walletInitialize :

  • Cinématique de consultation du contenu du Wallet client (sdkOperationName=GETWALLETDATA)
  • Cinématique d'ajout de carte au Wallet client (sdkOperationName=ADDCARD)
  • Cinématique de suppression d'un moyen de paiement du Wallet client (sdkOperationName=DELETEPAYMENTMEAN)

Ces différentes cinématiques sont décrites ci-après.

Une cinématique de consultation des données du Wallet client via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de gestion du Wallet auprès du serveur Worldline Sips via le service walletInitialize (avec sdkOperationName=GETWALLETDATA) ;
  • Effectuer un appel au service getWalletData depuis l'application mobile via le SDK Sips In-App.

Une fois le contenu du Wallet client récupéré, vous pouvez le présenter au client pour que celui-ci le manipule (ajout ou suppression d'un moyen de paiement du Wallet) ou effectue un paiement à partir d'une carte enregistrée.


image trop complexe pour être décrite, merci de prendre contact avec le support

Une cinématique d'ajout d'une carte au Wallet client via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de gestion du Wallet auprès du serveur Worldline Sips via le service walletInitialize (avec sdkOperationName=ADDCARD) ;
  • Effectuer un appel au service addCard depuis l'application mobile via le SDK Sips In-App.

image trop complexe pour être décrite, merci de prendre contact avec le support

Une cinématique de suppression d'un moyen de paiement du Wallet client via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de gestion du Wallet auprès du serveur Worldline Sips via le service walletInitialize (avec sdkOperationName=DELETEPAYMENTMEAN) ;
  • Effectuer un appel au service deletePaymentMean depuis l'application mobile via le SDK Sips In-App.

image trop complexe pour être décrite, merci de prendre contact avec le support

La requête et la réponse de la fonction walletInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par Sips In-App à 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'appel, par votre application mobile, du service souhaité (getWalletData, addCard ou deletePaymentMean).
03 L’identifiant commerçant est incorrect.
12 Les paramètres de la requête sont incorrects. Vérifiez les paramètres de la requête (l'erreur est indiquée dans le redirectionStatusMessage).
30 Le format de la requête est incorrect (l'erreur est indiquée dans le redirectionStatusMessage).
34 Problème de sécurité : par ex. le sceau calculé est incorrect.
40 Fonction non gérée.
99 Service temporairement indisponible.

3 cas sont possibles :

  • redirectionStatusCode = 00

Ce cas doit être suivi par l'appel, par votre application mobile, du service souhaité (getWalletData, addCard ou deletePaymentMean).

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

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 = 99

Problème de disponibilité du service. Vous devez essayer de renvoyer la requête.

Une fois la cinématique de gestion de Wallet terminée, vous devez analyser la réponse reçue pour connaitre le résultat du traitement. Cette réponse est fournie à l'application mobile en retour de l'appel à la fonction de gestion du Wallet.

État Champs de la réponse Action à réaliser
Opération de gestion du wallet prise en compte
walletLastActionDateTime renseignée avec la date/heure de la dernière action effectuée sur le wallet.
walletPaymentMeanDataList contient les moyens de paiement du wallet après mise à jour.
Afin d'éviter un appel à la fonction getWalletData pour consulter le contenu du Wallet d'un client lors d'un prochain paiement, vous pouvez stockez dans votre base client les données suivantes :
  • paymentMeanAlias
  • paymentMeanId
  • paymentMeanBrand
  • PanExpiryDate
  • maskedPan
Opération de gestion du wallet non prise en compte
walletLastActionDateTime renseigné avec une date/heure différente de la date/heure courante.
walletPaymentMeanDataList contient les moyens de paiement du wallet.
Si la mise à jour du Wallet est une action requise, tentez une nouvelle soumission de la requête.

Avec Sips In-App, vous pouvez effectuer une cinématique de consultation des données liées à la carte du porteur via l'opération paymentMeanInfoInitialize, avec le champ sdkOperationName renseigné à GETCARDDATA.

Vous pouvez utiliser cette cinématique notamment pour récupérer les marques de la carte du porteur afin de lui proposer le choix de la marque (pour plus de renseignement sur la réglementation "choix de la marque", vous pouvez consultez le guide de sélection de la marque).

Une cinématique de consultation des données carte via Sips In-App se déroule en 2 étapes :

  • Initialiser la cinématique de consultation des données carte auprès du serveur Worldline Sips via le service paymentMeanInfoInitialize (avec sdkOperationName=GETCARDDATA) ;
  • Une fois le numéro de carte saisie par le porteur, effectuer un appel au service getCardData depuis l'application mobile via le SDK Sips In-App.

Une fois les propriétés de la carte connues, vous pouvez, par exemple, présenter au porteur la ou les marques associées à sa carte, et lui proposer de choisir la marque souhaitée pour effectuer le paiement.


image trop complexe pour être décrite, merci de prendre contact avec le support

La requête et la réponse de la fonction paymentMeanInfoInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par Sips In-App à 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'appel, par votre application mobile, du service getCardData.
03 L’identifiant commerçant ou le contrat acquéreur sont incorrects.
12 Les paramètres de la transaction sont incorrects. Vérifiez les paramètres de la requête (l'erreur est indiquée dans le redirectionStatusMessage).
30 Le format de la requête est incorrect (l'erreur est indiquée dans le redirectionStatusMessage).
34 Problème de sécurité : par ex. le sceau calculé est incorrect.
40 Fonction non gérée.
99 Service temporairement indisponible.

3 cas sont possibles :

  • redirectionStatusCode = 00

Ce cas doit être suivi par l'appel, par votre application mobile, du service getCardData.

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

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 = 99

Problème de disponibilité du service. Vous devez essayer de renvoyer la requête.

Cette étape peut éventuellement être faite en parallèle de l'étape 2. Elle consiste en l'implémentation des intéractions entre votre application mobile et les services proposés au sein des SDK Sips In-App, selon la ou les cinématiques que vous souhaitez mettre en oeuvre.

Vous trouverez les détails pour implémenter les SDK en suivant ces liens :

Les étapes de test et d'intégration peuvent être réalisées à l'aide de l'environnement de recette.

L'URL de l'environnement de recette est : https://office-server.test.sips-services.com

Service d'initialisation pour le paiement /rs-services/v2/checkoutInApp/orderInitialize
Service d'initialisation pour la génération de Token de paiement /rs-services/v2/tokenInApp/paymentTokenInitialize
Service d'initialisation pour la gestion de wallet /rs-services/v2/walletInApp/walletInitialize
Service d'initialisation pour la consultation des données carte /rs-services/v2/paymentMeanInfoInApp/paymentMeanInfoInitialize
ID du commerçant 201040027570001
Version de la clé 1
Clé secrète H6znJWqPj9cTRFe9eT62ulurkb_Lrksbw4PFtMSVb74

Dans l’environnement de recette, le processus d’autorisation est simulé. Cela signifie qu’il n’est pas nécessaire d’utiliser des moyens de paiement réels pour effectuer des tests.

Vous pouvez utiliser les données suivantes pour vos tests :

Carte de test cf page "Cartes de test"
Cryptogramme 123
Date de validité doit être supérieure au mois en cours
Attention : la boutique de test est configurée en mode "transactionReference", sans génération automatique du transactionReference. Par conséquent, il est nécessaire que vous transmettiez cette information valorisée dans vos requêtes de test lorsque le service le demande.
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.

Une fois la connexion de votre application mobile à Sips In-App testée, vous êtes en mesure de valider la connexion à Sips In-App de production.

Au préalable, nous conseillons d’isoler votre application mobile du public pour éviter que des clients n'effectuent des transactions pendant cette phase de validation.

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

URL https://office-server.sips-services.com
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é)
Remarque : 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 ;
  • 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.

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, 97, 99,
    • Fraude : responseCode 34.

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

Pour compléter cette lecture, nous vous recommandons

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

Paramètres