Introduction

A qui s'adresse ce document ?

Ce document s’adresse aux commerçants qui souhaitent une intégration rapide et simple de la solution Sips . Il vous permet de démarrer avec le connecteur Sips Paypage POST sans personnalisation des pages de paiement.

Les options décrites dans ce guide sont les plus couramment utilisées.

Ce guide vous explique comment accepter des paiements :

  • en euros ,
  • avec les moyens de paiement Visa, Vpay, Electron, Mastercard, Maestro, PayP al et Paylib,
  • Sécurisés par 3-D Secure.

Vous utilisez Sips Office Extranet pour la gestion de caisse et recevez quotidiennement les journaux par mail.

Ce document est valable pour la version 2.18 du connecteur et les versions ultérieures.

Prérequis

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

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

Gestion de la clé secrète

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

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

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

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

Contacter l'assistance

Pour toute question technique ou demande d'assistance, nos services sont disponibles :

  • par téléphone au : +33 (0) 811 10 70 33 ;
  • par e-mail : sips@worldline.com.

Pour faciliter le traitement de vos demandes, veuillez communiquer votre identifiant de commerçant : merchantId (numéro à 15 chiffres).

Sips en bref

Sips est une solution de paiement e-commerce 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 , …).

Vous gardez le choix de votre établissement bancaire et des moyens de paiement acceptés.

Quotidiennement, Sips envoie par mail les journaux d’activité :

  • Le journal des transactions qui récapitule l’ensemble des transactions acceptées ou refusées.
  • Le journal des opérations qui récapitule les opérations de caisse que vous avez effectuées.
  • Le journal de rapprochement des transactions qui donne la vue financière des paiements crédités sur vos comptes.
  • Le journal de rapprochement des impayés qui rapproche les impayés de l’établissement bancaire (ex. contestation porteur) avec les transactions que vous avez acceptées.

Sips propose l’interface Sips Paypage pour connecter votre site Web à la plateforme de paiement.

Sips Paypage assure l’interface de paiement directement avec votre client via un navigateur Internet ou un mobile. Sips Paypage met donc à votre disposition des pages de paiements sécurisées, prêtes à l’emploi et accessibles par vos clients.

Sips Paypage s’accompagne d’une interface web de gestion de caisse : Sips Office Extranet . Elle vous permet de créer et gérer vos transactions. (validation, annulation, remboursement, ….)

Fonctionnement de Sips Paypage

Ref Nom Fréquence Description
a1 Requête de paiement Sips Paypage 24h/24h Requête de paiement envoyée par vous au serveur Sips
a2 Réponse automatique 24h/24h Réponse du serveur Sips retournée à vous, une fois le paiement effectué. Envoi automatique indépendant de l’action du client.
a3 Réponse manuelle 24h/24h Réponse du serveur Sips retournée à vous lorsque le client clique sur « continuer ». Envoi conditionné par l’action du client.
d1 Authentification du porteur 24h/24h Requête envoyée au serveur d’authentification 3-D Secure de la banque du porteur
e1 Demande d’autorisation 24h/24h Demande d’autorisation envoyée à votre établissement bancaire
e2 Remise en paiement 1/jour Remise en paiement envoyé par Sips vers l’établissement bancaire pour vous créditer
e3 Retour du paiement 24h/24h Retour de l’établissement bancaire sur le traitement d’acquisition des paiements
b Gestion de caisse 24h/24h Opération de caisse envoyée par vous au serveur Sips
c Journaux 1/jour Journaux envoyés par mail

Cinématique d'une transaction CB, VISA, MASTERCARD

Le parcours client est le suivant :

  • Validation du panier de votre page commerçant,
  • Redirection du client sur la page Sips de sélection du moyen de paiement,
  • Saisie des données carte,
  • Authentification du client sur une page de sa banque (si 3-D Secure),
  • Affichage du ticket de caisse par Sips ,
  • Confirmation de la prise en compte de la commande sur votre page commerçant.

Dans cette cinématique que la saisie des données de la carte s'effectue chez Sips .Vous n’avez pas connaissance de ces données sensibles.

Cinématique d'une transaction PayPal

Le parcours client est le suivant :

  • Validation du panier sur votre page commerçant
  • Redirection du client sur la page de sélection du moyen de paiement Sips
  • Identification du client sur une page PayPal et validation du moyen de paiement
  • Affichage du ticket de caisse par Sips
  • Confirmation de la prise en compte de la commande sur votre page commerçant

Cinématique Paylib

Le parcours client est le suivant :

  • Validation du panier sur votre page commerçant
  • Redirection du client sur la page Sips de sélection du moyen de paiement
  • Identification du client sur une page Paylib
  • Choix et validation du moyen de paiement sur une page Paylib
  • Affichage du ticket de caisse par Sips
  • Confirmation de la prise en compte de la commande sur votre page commerçant

Le client a également la possibilité d’effectuer un paiement mobile via l’application mobile Paylib ou l’application mobile commerçant. Le parcours client sera le même.

Identification des transactions

Les transactions de votre boutique sont identifiées de manière unique grâce au champ transactionReference .

Cet identifiant est calculé par Sips ou pas vous lors de la création de la transaction. Le couple (transactionReference, merchantId) identifie de manière unique la transaction pendant toute la vie de votre boutique.

Démarrer avec Sips Paypage POST en 5 étapes

Pour accepter des paiements via Sips vous devez avoir préalablement signé :

  • Un contrat de vente à distance e-commerce/vente par correspondance (VPC) avec votre banque
  • Un contrat d’acceptation avec le revendeur de la solution Sips .

La souscription au service 3-D Secure de Visa et MasterCard qui sécurise les paiements internet est une clause obligatoire du contrat de vente à distance avec votre banque.

Pour pouvoir accepter les paiements PayPal, vous devez également avoir signé un contrat avec PayPal. Votre compte commerçant PayPal doit également être configuré de manière à autoriser l’appel à Sips (cf annexe "paramétrer son compte PayPal").

Étape 1 : inscrire la boutique

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.

Etape 2 : Connecter votre site à Sips Paypage

Vous devez intégrer le connecteur Sips Paypage POST pour connecter votre site commerçant au serveur de paiement Sips .

Vous devez donc mettre en place les liens a1 (requête de paiement), a2 et a3 (réponse de paiement) décrits dans ce schéma :

Note: bien que la réponse automatique ne soit pas obligatoire, il est fortement conseillé de l’implémenter.

Si le client ne clique pas sur « continuer », la réponse manuelle ne sera pas envoyée et vous n’aurez pas de réponse venant de Sips vous confirmant le traitement de la transaction.

Générer la requête de paiement

La requête paiement est envoyée depuis une page de votre site web vers le serveur Sips via un formulaire web avec la méthode POST. Ce formulaire doit pointer vers l’URL du serveur de paiement Sips et contenir les champs suivants :

Donnée du formulaire Présence Description
Data Obligatoire Ensemble des champs de la requête de paiement (champs décrits ci-dessous dans la partie « construire la requête de paiement : donnée Data »)
InterfaceVersion Obligatoire L’interface version définit la version de la requête et de la réponse échangée avec le serveur de paiement. Les champs décrits ci-après correspondent à l' interfaceVersion HP_ 2.27 . Si vous utilisez une version antérieure du connecteur, il est possible que certains champs ne soient pas disponibles et ne puissent être utilisés.
Seal Obligatoire Signature de la donnée Data qui permet de garantir la sécurité de la requête de paiement
Encode Optionnel Dans le cas où la donnée Data comporte des caractères spéciaux, vous devez changer l’encodage. La valeur du champ Encode précise la méthode d’encodage utilisée pour la donnée Data. En cas d’encodage, le seal est calculé sur la donnée data encodé.

Valeurs:

  • Base64 : encodage du champ data en base 64
  • Base64URL : encodage du champ data en base64URL
SealAlgorithm Optionnel Algorithme utilisé pour le calcul de l’empreinte de la donnée Data

Valeurs :

  • HMAC-SHA-256 : L'algorithme utilisé est HMAC-SHA-256
  • HMAC-SHA-512 : L'algorithme utilisé est HMAC-SHA-512
  • SHA-256 : L'algorithme utilisé est SHA-256
Note: Par défaut, le sceau est calculé avec l'algorithme SHA-256, 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”.

Construire la requête de paiement : donnée Data

La donnée Data est composée de plusieurs champs, elle contient toutes les informations relatives à la transaction.

Elle est fournie sous la forme d’une chaîne de caractères respectant la syntaxe suivante :

      <nomChamp1>=<valeurChamp1>|<nomChamp2>=<valeurChamp2>|… |<nomChampN>=<valeurChampN>
    

La donnée Data est composée des champs suivants :

  • Champs obligatoires
Champs Format Description
amount N12 Montant de la transaction. Il doit être transmis dans la plus petite unité de la devise. Ex : pour l’Euro, un montant de 10,50€ doit être transmis sous la forme 1050.
currencyCode N3 (restricted values / ISO4217) Code de la devise de la transaction. Ce code est compatible ISO 4217. Ex : le code de l’euro est 978.
keyVersion N10 Version de la clé secrète du commerçant utilisée pour calculer le seal du message. Ex : KeyVersion=1 pour la 1ère clé générée à l’inscription de la boutique.
merchantId N15 Identifiant de la boutique, fourni par Sips au commerçant lors de l’inscription de sa boutique.
normalReturnUrl ANS512 (url) URL du commerçant pour le retour à la boutique en cas d’acceptation ou de refus de la transaction (réponse manuelle). Ex : https://www.monsite.fr/RetourPaiement
automaticResponseUrl ANS512 (url) URL fournie par le commerçant et utilisée par le serveur de paiement pour notifier au commerçant de manière online et automatique le résultat de la transaction (réponse automatique).

NB : champ non obligatoire mais utilisation fortement recommandée pour que vous receviez la réponse de paiement même si le client ne clique pas sur « continuer »

  • Principaux champs métiers facultatifs qui vous permettent de faciliter la correspondance entre votre système d’information et le serveur de paiement Sips
Champs Format Description
customerId ANS19 (restrictedString) Identifiant du client
customerEmail ANS128 (email) E-mail du client
orderId ANS32 Numéro de commande associé à la transaction de paiement.
returnContext ANSU255 (extendedString) Contexte de la commande transmis dans la requête de paiement et restitué sans modification dans la réponse et le journal des transactions. Vous pouvez y stocker toute les informations qui facilitent le traitement de la réponse.
  • Champs CB,Visa,Mastercard,Vpay, Electron, Maestro, Paylib : Pas de champ spécifique
  • Champs PayPal (champs disponibles depuis la version HP_2.18)
Champs Format Description
addrOverride ANS20 (restricted values) Indicateur vous permettant :
  • d’afficher l’adresse de livraison sur les pages PayPal,
  • de savoir, si l’adresse à afficher est celle que vous communiquez ou s’il s’agit de celle stockée par PayPal
  • de déterminer si vous pouvez modifier l’adresse stockée par PayPal.

Valeurs :

  • NO_OVERRIDE : PayPal affiche l'adresse enregistrée par le client sur son compte PayPal.
  • OVERRIDE : PayPal affiche l'adresse communiquée par le commerçant, l'adresse enregistrée par le client sur son compte PayPal est supprimée.
  • NO_DISPLAY (Valeur par défaut) : Aucune adresse n'est affichée. L'adresse envoyée par le commerçant n'est pas prise en compte par PayPal
invoiceId AN127 Numéro de commande, équivaut à l’orderId mais doit être unique chez PayPal. Obligatoire pour l’utilisation de PayPal.
landingPage AN5 (restricted values) Indicateur vous permettant de masquer le formulaire de souscription sur les pages PayPal.

Valeurs :

  • true : La page de souscription est affichée
  • false : La page de souscription n'est pas affichée, PayPal affiche directement la page d'identification
mobile AN5 (restricted values) Indicateur vous permettant de préciser si le terminal utilisé par le client est le mobile

Valeurs :

  • true : L'appareil utilisé est un mobile
  • false : L'appareil utilisé n'est pas un mobile
orderDescription ANS127 Description de la commande
Sécuriser la requête

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

De ce fait, il est nécessaire de renforcer la sécurité pour assurer l’intégrité des paramètres de la transaction envoyée. 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 ;
Note: 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 .
Signer l'empreinte de la requête de paiement

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 qui doit être envoyé sous forme hexadécimale dans le champ POST nommée Seal.

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

Il existe 2 méthodes pour signer l’empreinte de la donnée Data :

Pour l’algorithme HMAC-SHA256 :

  • Utilisation de la donnée Data uniquement (encodée si l’option correspondante est choisie)
  • Utilisation de la clé secrète partagée pour générer la variante HMAC du message
  • Codage UTF-8 des données constituant le résultat de l’opération précédente
  • « Hashage » HMAC-SHA256 des octets obtenus
Table 1. En résumé
HMAC-SHA256( UTF-8(Data), UTF-8(secreteKey))

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 du champ 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
Table 2. En résumé
SHA256( UTF-8(Data+secretKey))
Exemples de code Hmac Sha256
  • Exemple d’encodage Hmac Sha256 en Php 5
            <?php
    
    …
    
    // Seal computation thanks to hash sorted data hash with merchant key
    
    $data_to_send= utf8_encode($data)
    
    $seal=hash_hmac('sha256', $data_to_send, $secretKey);
    
    …
    …
    
    ?> 
          

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

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

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

            using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Text;
    using System.Windows.Forms;
    using System.Security.Cryptography;
    
    namespace ExampleDotNET
    {
        public partial class Form1 : Form
        {
            public Form1()
            {
                InitializeComponent();
            }
    
            private void cmdGO_Click(object sender, EventArgs e)
            {
                String sChaine = data.Text;
                UTF8Encoding utf8 = new UTF8Encoding();
                Byte[] encodedBytes = utf8.GetBytes(sChaine);
            
                byte[] shaResult;
                
                HMAC hmac = new HMAC.Create("HMACSHA256");
                var key = "YourSecretKey";
                hmac.Key = utf8.GetBytes(key); 
                hmac.Initialize();
    
                shaResult = hmac.ComputeHash(encodedBytes);
    
                lblHEX.Text = ByteArrayToHEX(shaResult);
            }
    
            private string ByteArrayToHEX(byte[] ba)
            {
                StringBuilder hex = new StringBuilder(ba.Length * 2);
                foreach (byte b in ba)
                    hex.AppendFormat("{0:x2}", b);
                return hex.ToString();
            }
    
        }
    }
          
Exemples de code Sha256
  • Exemple d’encodage Sha256 en Php 5
      <?php
echo hash('sha256', $data.$secretKey);
?> 
    

Le jeu de caractères UTF-8 doit être utilisé pour les données Data et secretKey. Pour effectuer une conversion de ISO-8859-1 à UTF-8, faites appel à la fonction utf8_encode .

  • Exemple d’encodage Sha256 en Java
      import java.security.MessageDigest;

public class ExampleSHA256 {

/**
 * 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
{
  MessageDigest md = MessageDigest.getInstance("SHA-256");
  md.update((Data+secretKey).getBytes("UTF-8"));

  return encodeHexString(md.digest());
}

/**
 * @param args
 */
public static void main(String[] args) {
try {
System.out.println (computeSeal("parameters", "key"));
} catch (Exception e) {
e.printStackTrace();
}
}
}
    
  • Exemple d’encodage Sha256 en .NET

Exemple complété à l’aide d’un simple formulaire appelé « Form 1 » contenant deux champs de texte à renseigner : data, txtSecretKey et un autre à 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 + txtSecretKey.Text;
            UTF8Encoding utf8 = new UTF8Encoding();
            Byte[] encodedBytes = utf8.GetBytes(sChaine);
        
            byte[] shaResult;
            SHA256 shaM = new SHA256Managed();
            shaResult = shaM.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();
        }

    }
}
    

Envoyer la requête à Sips

La demande de paiement est une requête HTTPS POST adressée à Sips Paypage POST .

Exemple de requête dans le formulaire web (Data non encodé. Les champs optionnels sealAlgotrihm et encode ne sont pas renseignés).

      <form method="post" action="https://url.vers.serveur.sips/paymentInit">
    <input type="hidden" name="Data" value="amount=55|currencyCode=978|merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|transactionReference=534654|keyVersion=1">
    <input type="hidden" name="InterfaceVersion" value="HP_2.18">
    <input type="hidden" name="Seal" value="21a57f2fe765e1ae4a8bf15d73fc1bf2a533f547f2343d12a499d9c0592044d4">
    <input type="submit" value="Payer">   
  </form> 
    

Traitement des erreurs

Voici une liste des erreurs que vous pourriez rencontrer et les messages pour chacun de ces cas. Si l’erreur persiste, contactez l’assistance.

Etat Exemple de message d’erreur Action à réaliser
MerchantId inexistant Merchant ID (merchantId) not found : findMerchantPoi [220555555550002] is not found [5c62b84e3ae83d] Vérifiez le merchantId utilisé avec celui retourné par Sips après l’inscription.
Algorithme de seal incorrect Invalid field value : Invalid sealAlgorithm value (SHA-257) [609eac90a8ee1e]] Vérifiez l’algorithme seal utilisé (champ seal)
Erreur clé secrète Invalid signature : rge7gesgd86g556dgv4r89g4d6 [609aec21985569] La signature calculée par Sips à la réception de la requête n’est pas identique à celle que vous avez envoyée.
  • Lors des tests en simulation, vérifiez la valeur de la clé utilisée avec celle fournie plus loin dans ce document (cf étape 3)
  • Sur le serveur de production, vérifiez la clé utilisée avec celle récupérée sur Sips Download
Version de clé invalide Invalid field value : Unable to find a valid key for the following keyVersion=0 [609aec2b60b1d0] Sips ne trouve pas la version de clé que vous indiquez (champ keyVersion).
  • Lors des tests en simulation, vérifiez la version de la clé utilisée avec celle fournie plus loin dans ce document (cf étape 3)
  • Sur le serveur de production, vérifiez la version de la clé utilisée avec celle récupérée sur Sips Download
Champ Encode incorrect Invalid keyword : ENCODE [609aecdee11d52] Vérifiez que l’algorithme de l’encodage que vous utilisez est correctement renseigné dans le champ encode.
URL de retour incorrecte Technical problem : code=30 message=normalReturnUrl is invalid https:// [609aec31b00b94] Vérifiez la syntaxe de l’URL que vous indiquez dans le champ normaReturnUrl
Note: Les messages sont affichés sur la plateforme de simulation pour vous aider à valider l’intégration de votre site Web. Pour des raisons de sécurité, des messages d’erreur beaucoup plus simples sont affichés sur la plateforme de production. Ex « Erreur lors du traitement de la requête de paiement. Contactez votre commerçant ».

Traiter la réponse de paiement

Une fois le paiement terminé :

  • Sips affiche le ticket de caisse
  • Une réponse automatique vous est envoyée à l’URL contenue dans le champ autoResponseUrl de la requête (optionnel mais fortement conseillé).
  • Sips invite le client à revenir sur votre site grâce à l’URL renseignée dans le champ normalReturnUrl de la requête. L'action faite par le client déclenche l'envoi d'une réponse manuelle.

Ces quatre champs sont retournés par Sips dans les réponses (automatique et manuelle) :

Champs Description
Data Contient les champs de réponse. Respecte la même syntaxe que le champ Data de la requête de paiement.
Encode Type d’encodage utilisé. S’il vaut base64 ou base64url, le champ Data doit être décodé en Base64/Base64Url pour retrouver la chaîne des champs concaténés.
Seal Signature du champ Data qui permet de garantir la sécurité de la réponse de paiement.
InterfaceVersion Valeur et numéro de version de l’interface utilisée.

Vérifier la sécurité de la réponse

Tout d’abord vous devez vérifier la sécurité du message retourné en recalculant le Seal selon la même méthode que celle utilisée pour la requête. Ensuite, comparez le champ Seal calculé avec celui de la réponse Sips .

Si les Seal sont identiques, vous poursuivez en traitant la réponse de paiement contenue dans le champ Data.

Dans le cas contraire, vous devez stopper le traitement: vérifier la clé secrète et/ou l’algorithme utilisés et si besoin contacter le support technique.

Analyser la réponse de paiement

La réponse de paiement contenue dans le champ Data est composée :

  • Champs génériques
Champs Format Description
amount N12 Montant de la transaction. Le montant est transmis dans la plus petite unité de la devise. Exemple pour l’Euro : un montant de 10,50 Euros doit être transmis sous la forme 1050.
currencyCode N3 (restricted value / ISO4217) Code de la devise de la transaction. Ce code est compatible ISO 4217.
customerId AN19 (restrictedString) Identifiant du client
customerEmail ANS128 (email) E-mail du contact
transactionReference AN35 Identifiant unique de la transaction par commerçant.
guaranteeIndicator A1 (restricted values) Niveau de garantie de la transaction (tableau des valeurs ci-dessous).
orderId ANS32 Numéro de commande associé à la transaction de paiement
responseCode N2 (restricted values) Code réponse du serveur Sips (tableau des valeurs ci-dessous).
acquirerResponseCode AN2 (restricted values) Code réponse retourné par l’acquéreur lors d’une demande d’autorisation (tableau des valeurs ci-dessous).
authorisationId AN10/ANS32 Identifiant d’autorisation, retourné par le serveur d’autorisation de la banque du client en cas d’accord (non renseigné en cas de refus).
maskedPAN ANS19 Numéro de PAN masqué.
panExpiryDate N6 (YYYYMM) Date d'expiration du PAN.
paymentMeanBrand ANS20 (restricted values) Nom du moyen de paiement utilisé par le client. Valeurs :
  • CB
  • VISA
  • MASTERCARD
  • ELECTRON
  • VPAY
  • MAESTRO
  • PAYPAL
returnContext ANSU255 (extendedString) Contexte de la commande transmis dans la requête de paiement et restitué sans modification dans la réponse et le journal des transactions.
  • Champs si paiement carte
Champs Format Description
holderAuthenStatus ANS20 (restricted values) Résultat du processus d’authentification porteur (tableau des valeurs ci-dessous).
cardProductCode AN5 Code produit de la carte.
cardProductName ANS70 Libellé du code produit de la carte.
issuerCode AN6 Code émetteur de la carte
issuerCountryCode A3 (restricted values) Code pays de l’émetteur de la carte
  • Champs si paiement PayPal

    pas de champ spécifique
  • Valeurs des champs à analyser

Le champ responseCode donne le résultat de l’acceptation.

La valeur 00 dans le champ responseCode signifie que le paiement est accepté.

En cas de refus ( responseCode différent de 00), le champ acquirerResponseCode précise la nature du refus de la banque (si paiement carte) ou du serveur PayPal (si paiement PayPal).

responseCode Description Type refus
00 Transaction acceptée
05 Transaction refusée Bancaire
34 Suspicion de fraude (seal erroné) Fraude
75 Nombre maximum de tentatives atteint Moyen de paiement
90 Service temporairement indisponible Technique
97 Session expirée (aucune action de l'utilisateur pendant 15 min), transaction refusée Technique
99 Problème temporaire au niveau du serveur Sips Technique
holderAuthentStatus Description Valeur 3-D
ATTEMPT Le client n’a pas eu à s’authentifier. 3D_ATTEMPT
CANCEL Le client a abandonné durant l'authentification. 3D_ABORT
ERROR Problème technique lors de l’authentification 3DS. 3D_ERROR
FAILURE Le client n’a pas réussi à s’authentifier (erreur de mot de passe). 3D_FAILURE
NOT_ENROLLED La carte utilisée n’est pas enrôlée 3-D Secure. 3D_NOTENROLLED
NOT_PARTICIPATING Le client ne s’est pas authentifié car :
  • le type de carte n’est pas supporté par le 3DS ;
  • vous n’êtes pas inscrit au programme 3DS.
SSL
SUCCESS Le porteur de la carte s’est authentifié correctement. 3D_SUCCESS
guaranteeIndicator Description
Y Paiement 3D garanti
N Paiement 3D non garanti
U Garantie 3D non définie
Paiement non 3D
acquirerResponseCode Description Correspondance responseCode
00 Transaction approuvée ou traitée avec succès 00
02 Contacter l'émetteur du moyen de paiement 02
03 Accepteur invalide 03
04 Conserver le support du moyen de paiement 05
05 Ne pas honorer 05
07 Conserver le support du moyen de paiement, conditions spéciales 05
08 Approuver après l'identification 05
12 Transaction invalide 12
13 Montant invalide 05
14 Coordonnées du moyen de paiement invalides 14
15 Émetteur du moyen de paiement inconnu 05
17 Paiement interrompu par le client 17
24 Opération impossible 05
25 Transaction inconnue 05
30 Erreur de format 30
31 Id de l'organisation d'acquisition inconnu 05
33 Moyen de paiement expiré 05
34 Suspicion de fraude 34
40 Fonction non supportée 05
41 Moyen de paiement perdu 05
43 Moyen de paiement volé 34
51 Provision insuffisante ou crédit dépassé 05
54 Moyen de paiement expiré 05
56 Moyen de paiement manquant dans le fichier 05
57 Transaction non autorisée pour ce porteur 05
58 Transaction interdite au terminal 05
59 Suspicion de fraude 05
60 L'accepteur du moyen de paiement doit contacter l'acquéreur 05
61 Excède le maximum autorisé 05
62 Transaction en attente de confirmation de paiement 05
63 Règles de sécurité non respectées 05
65 Nombre de transactions du jour dépassé 05
68 Réponse non parvenue ou reçue trop tard 05
75 Nombre de tentatives de saisie des coordonnées du moyen de paiement dépassé 75
87 Terminal inconnu 05
90 Arrêt momentané du système 90
91 Emetteur du moyen de paiement inaccessible 90
92 La transaction ne contient pas les informations suffisantes pour être redirigée vers l'organisme d'autorisation Transaction dupliquée 90
94 Transaction dupliquée 90
96 Mauvais fonctionnement du système 90
97 Requête expirée: transaction refusée 90
98 Serveur inaccessible 90
99 Incident technique 99
A1 Paiement refusé par l'acquéreur (données 3-D Secure manquantes dans la demande d'autorisation). 05

Traitement de la réponse

Etat Champs de la réponse Action à réaliser
Paiement 3-D Secure 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 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 autre moyen de paiement en générant une nouvelle requête.
Refus bancaire responseCode = 05 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 responseCode = 34 Autorisation refusée pour cause de fraude. Ne livrez pas la commande.
Refus nombre max d’essais atteint responseCode = 75 Le client a fait plusieurs tentatives toutes échouées car les informations saisies n’étaient pas correctes. Deux possibilités :
  • Difficulté pour votre client à renseigner les informations carte
  • Tentative de carding (recherches de numéros de cartes possibles)
Prenez contact avec votre client pour définir avec lui 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.

Etape 3 : Tester la connexion à Sips Paypage

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

Pour effectuer ce test, il faut utiliser les identifiants suivants :

URL https://payment-webinit.simu.sips-atos.com/paymentInit
merchantId 002001000000002
secretKey 002001000000002_KEY1
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.

Tester des transactions CB, VISA, MASTERCARD

  • Le numéro de carte (PAN) doit comporter de 16 à 19 chiffres
  • 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
    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 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 Sips 05).

Note: Si le code réponse 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.

Tester des transactions PayPal

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.

Tester des transactions Paylib

Paylib n’est pas disponible en simulation.

Etape 4 : Valider la connexion en production

Une fois la connexion de votre site web à testée, vous êtes à présent en mesure de valider la connexion à Sips Paypage POST de production.

Pour ce faire, vous devez changer l’URL pour vous connecter au serveur Sips de production en utilisant les identifiants reçus lors l’inscription ( merchantId , secretKey et keyVersion ).

URL https://payment-webinit.sips-atos.com/paymentInit
merchantId Identifiant de la boutique reçu par mail
secretKey Clé secrète que vous récupérez via 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 quatre paramètres ce qui conduit systématiquement à une erreur.

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

Comment valider le bon fonctionnement en production

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.

Étape 5 : démarrer en production

Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’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).

Annexes

Créer votre compte PayPal

Afin d'utiliser le moyen de paiement PayPal sur votre site Web, vous devez posséder un compte PayPal. Il doit s'agir d'un compte professionnel (le type du compte est choisi lorsque vous vous enregistrez sur http://www.PayPal.com ).

Si vous avez plusieurs boutiques actives, nous vous suggérons de créer un compte PayPal pour chacune.

Paramétrer son compte PayPal

Sur votre compte PayPal, vous devez, en tant que commerçant, autoriser le prestataire de services de paiement (PSP) à appeler l'API de PayPal.

Note: Les captures des pages PayPal sont données ici à titre indicatif. Il se peut que PayPal modifie ses pages.

Dans votre compte PayPal entreprise, allez dans Préférences , Mes vente s puis Accès à l'API :

Cliquez sur le lien Ajouter ou modifier des droits d'accès API.

La fenêtre Ajouter de nouveaux droits d'accès à un tiers s'ouvre. Dans le champ textuel, entrez le compte technique Sips dlfr-sipspaypal_api1.atosorigin.com puis cliquez sur Rechercher .

Sélectionnez les options suivantes :

  • Utiliser PayPal Option+ pour traiter vos paiements ;
  • Effectuer un remboursement pour une transaction spécifique ;
  • Autoriser et collecter vos transactions PayPal .

Cliquez ensuite sur le bouton Ajouter .

Clé secrète

Télécharger la clé secrète

Connectez-vous à Sips Download grâce aux identifiants qui vous ont été retournés par Sips lors de l’inscription de votre boutique

Allez dans l’onglet « clés secrètes »

Vous pouvez télécharger votre clé secrète :

Révocation et demande de renouvellement de clé secrète

Connectez-vous à Sips Download grâce aux identifiants qui vous ont été retournés par Sips lors de l’inscription de votre boutique.

Allez dans l’onglet « clés secrètes ».

Cliquez sur l’icône suivante (dans la colonne désactivation) en face de la clé que vous souhaitez révoquer. La révocation prend effet immédiatement.

Une fois que Worldline a confirmé la désactivation de la clé, le statut de la clé passe d’active « oui » à « non ».

Une fois votre clé révoquée, demandez le renouvellement de votre clé en cliquant sur le bouton :

Le message ci-dessous s’affiche et vous confirme que votre demande a bien été envoyée :

Une fois que Worldline a validé la génération d’une nouvelle clé secrète, une nouvelle clé apparait dans l’interface. Vous pouvez la télécharger.

Réglementation des paiements

La solution Sips est conforme à la règlementation en vigueur définie par CB, Visa et Mastercard.

La sécurisation des paiements (PCI)

PCI DSS est un standard de sécurité international dont les objectifs sont d’assurer la confidentialité et l’intégrité des données des porteurs de cartes, et ainsi de sécuriser la protection des données carte et des transactions. Vous et les prestataires de paiement sont tenus de s’y conformer, à des degrés divers en fonction de l’importance de leur activité. La solution Sips est certifiée PCI DSS depuis 2006.

En utilisant Sips Paypage , vous n’avez pas accès aux données du porteur de carte et n’avez pas besoin d’être certifié PCI DSS. Les données carte sont gérées par Worldline .

Le choix de la marque lors du paiement (MIF)

La solution Sips 2.0 est soumise à la réglementation européenne MIF (JO EU 2015/751 L123 du 19/05/2015). Parmi ces règles, la « sélection de la marque » vous impose de proposer au client porteur d’une carte cobadgée le choix de la marque au moment du paiement, ce qui impacte la page de paiement.

Une carte cobadgée est une carte qui supporte au moins deux marques. La plupart des cartes émises en France sont cobadgées avec CB (carte CB/VISA, CB/MASTERCARD, CB/MAESTRO…).

Ainsi vous devez laisser le choix de la marque au client porteur de ces cartes cobadgées. À titre d’illustration, l’écran ci-dessous présente un exemple de carte cobadgée CB + Visa avec CB en marque par défaut. Le client peut changer la marque en cliquant sur le lien en bas de l’écran.

Note: Pour les cartes non-cobadgées, aucun choix de marque n’est proposé.

Pour en savoir plus

Si vous souhaitez implémenter d’autres moyens de paiement ou options, veuillez-vous référer aux documentations associées.

Cette liste n’est pas exhaustive mais vous présente les documents complémentaires pour vous aider à aller plus loin dans la mise en œuvre de Sips .

Guide Pourquoi le lire ?
Dictionnaire des données Ce guide vous permet de connaître la définition et l’ensemble de valeurs des champs des connecteurs et journaux.
Présentation fonctionnelle Ce guide vous permet d’avoir une vue d’ensemble des fonctionnalités de Sips et des options disponibles auxquelles vous pouvez souscrire.
Guide de configuration des fonctionnalités Ce guide vous explique la mise en œuvre des fonctionnalités Sips .
Description des journaux Ce guide décrit le contenu des journaux envoyés par Sips .
Personnalisation de Sips Paypage pour les boutiques Ce guide vous explique comment personnaliser les pages de paiement afin qu’elles aient une charte graphique similaire au reste de votre site.
OneClick Ce guide décrit la solution OneClick qui permet à vos clients de payer en un clic sans avoir à ressaisir leurs données cartes.
Sips Message Ce guide explique comment implémenter la solution Sips message qui vous permet d’envoyer à vos clients une notification de paiement par mail ou par SMS .
Sips Download Ce guide explique comment télécharger la documentation et votre clé secrète via l’extranet Sips Download .
Sips Office Extranet Ce guide décrit l’ensemble des actions de gestion de caisse que vous pouvez effectuer via Sips Office Extranet .
Gestion de la lutte contre la fraude – Go-no-Go Ce guide explique le fonctionnement, la configuration et l’utilisation du moteur de lutte contre la fraude Go-No-Go. Il vous permet de définir les règles d’acceptation fraude que vous souhaitez mettre en place lors du paiement.
Sips Paypage POST Ce guide décrit et explique comment implémenter l’intégralité des options du connecteur .
Intégration American Express Ce guide vous explique comment intégrer les cartes American Express.