Introduction
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 Sips Walletpage POST jusqu’au démarrage en production.
À qui s’adresse ce document
Ce document est destiné aux commerçants qui souhaitent souscrire à l’offre Worldline Sips et utiliser un connecteur fondé sur les échanges HTTPS en mode POST entre leur site Web et les serveurs Worldline Sips afin de permettre à leurs clients de gérer leur wallet oneClick ou leur wallet abonné.
C’est un guide d’implémentation qui s’adresse à l’équipe technique du commerçant.
Pour avoir une vue d’ensemble de la solution Worldline Sips, nous vous conseillons de consulter les documents suivants :
- Présentation fonctionnelle
- Guide de configuration des fonctionnalités
- Guide du paiement OneClick
- Guide du paiement par abonnement
Prérequis
Une connaissance élémentaire des standards relatifs aux langages de programmation Web pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour développer la connexion à Sips Walletpage POST.
Gestion de la clé secrète
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).
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.
Comprendre la gestion des wallets client avec Sips Walletpage POST
Le principe général d’un processus de gestion de wallet est le suivant :
![image sur le principe général d’un processus de gestion de wallet](../../resources/images/fr/WLSIPS.321-sips-walletpage-soap/comprendre-gestion-wallet-walletpage-soap-json.png)
1. Lorsque le client initialise l’étape de gestion de wallet, une
requête doit être envoyée au connecteur Sips Walletpage POST dont
Worldline fournit l’URL. La requête est alors vérifiée, et
chiffrée si elle est valable (elle est nommée RedirectionData
dans le système). La requête
est envoyée au moyen d’un formulaire en mode POST via HTTPS. Toute autre
solution capable d’envoyer une requête de cette nature fonctionne
également.
2. Le site du commerçant redirige l’application appelante vers l’interface de gestion de wallet avec la requête chiffrée. Celle-ci est déchiffrée et Sips Walletpage permet au client d’effectuer différentes opérations sur son wallet. Pour que le client puisse retourner sur votre site, une réponse est créée et envoyée à l’URL de réponse fournie dans le flux n°1.
Il y a deux notifications de réponses indépendantes :
3. Le serveur de gestion de wallet envoie la réponse manuelle via HTTP(S) POST vers l’URL de réponse manuelle, laquelle est fournie dans la requête de gestion de wallet lorsque le client clique sur « Retour à la boutique » sur la page de gestion de wallet. C’est pourquoi l’URL de réponse normale est également la page vers laquelle le client est redirigé à l’issue des opérations de gestion de wallet. Comme il n’y a aucune garantie que le client clique sur ce lien, la réception de la réponse manuelle n’est pas garantie non plus.
4. Les réponses automatiques sont envoyées indépendamment des réponses manuelles. Elles utilisent également les requêtes HTTP(S) POST envoyées par les serveurs de gestion de wallet mais, cette fois-ci moyennant l’URL de la réponse automatique précisée dans la requête de gestion de wallet. Vous recevez la réponse lorsque le client cliquera sur le bouton « retour à la boutique » ou si la session de gestion du wallet aura expiré.
Démarrer avec Sips Walletpage POST en 5 étapes
Étape 1 : souscrire au service
Si votre boutique n’a pas encore été inscrite, vous devez remplir le formulaire d’inscription (en demandant le service abonnement ou le service oneClick) envoyé par Worldline et le retourner à ce dernier.
Si votre boutique est déjà inscrite sur Worldline Sips, vous devez demander au contact technique d’activer le service abonnement ou le service oneClick.
Si ce n’est pas précisé, Worldline Sips définit une base wallet dédiée à votre boutique.
Étape 2 : gérer le wallet de vos clients
La requête de gestion de wallet est une requête HTTPS POST adressée au connecteur de gestion de wallet. Vous devez envoyer la requête via un formulaire HTML au moyen de la méthode POST.
Générer la requête de gestion de wallet
Trois données obligatoires sont renseignées dans les requêtes de gestion du wallet :
Nom de la donnée | Description |
---|---|
Data | Contient toutes les informations relatives à la gestion du wallet. |
InterfaceVersion | Définit la version de la requête et de la réponse échangée avec le serveur Worldline Sips. |
Seal | Utilisé pour valider l’intégrité des données échangées. La donnée Seal est calculée à l’aide de la donnée Data et de la clé secrète. |
Des données optionnelles supplémentaires sont disponibles :
Nom de la donnée | Description |
---|---|
Encode | Précise la méthode utilisée pour encoder la donnée Data. |
SealAlgorithm | Précise l’algorithme utilisé pour calculer la donnée Seal. |
Syntaxe de la donnée Data
La donnée Data est construite conformément au format suivant :
<nomChamp1>=<valeurChamp1>|<nomChamp2>=<valeurChamp2>|…|<nomChampN>=<valeurChampN>
Tous les champs nécessaires pour la gestion du wallet (voir les détails dans le dictionnaire de données) doivent être inclus dans la chaîne de caractères. L’ordre des champs n’a pas d’importance.
merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|merchantWalletId=w5346|keyVersion=1|requestDateTime=2015-08-05T16:18:09.415+02:00
Il est possible d'avoir une liste de valeurs pour un même champ :
..|nomChamp=valeur1,valeur2, … ,valeurX|…
Exemple avec le champ paymentMeanBrandList valorisé avec VISA et MASTERCARD :
…|normalReturnUrl=https://www.normalreturnurl.com|merchantId=201010314150000|keyVersion=1|merchantWalletId=2|paymentMeanBrandList=VISA,MASTERCARD|requestDateTime=2017-05-26T11:09:01.487+02:00|keyVersion=1|…
Si le champ est un container, vous devez utiliser un point entre le nom du container et le nom du champ :
..|Container.nomChamp1=valeurChamp1|container.nomChamp2=valeurChamp2|……
Exemple pour le champ customerContact contenant l’email (moi@email.com) ainsi que le nom et prénom (Jean Dupont) du client :
…|customerContact.email=moi@email.com|customerContact.firstname=Jean|customerContact.lastname=Dupont|…
Encodage de la donnée Data
Si la donnée Data comporte des caractères spéciaux (comme par exemple des caractères accentués) alors elle doit être encodée en base64 ou base64Url.
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. 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.
Comment sécuriser la requête
La sécurisation de la requête est effectuée en calculant la valeur « hashée » conformément aux paramètres de la transaction (donnée Data). Ensuite, la clé secrète y est ajoutée. Toutes les chaînes de caractères sont converties en UTF-8 avant le « hashage ».
L’algorithme de « hashage » génère un résultat irréversible. Lorsqu’un tel message est reçu, le destinataire doit recalculer la valeur « hashée » pour la comparer à celle reçue. Toute différence indique que les données échangées ont été falsifiées ou que le destinataire et l’émetteur ne partagent pas la même clé secrète.
Le résultat doit être envoyé sous forme hexadécimale dans la donnée nommée Seal.
Calcul de la donnée Seal
Algorithme HMAC-SHA
La valeur de la donnée Seal est calculée comme suit :
- Contenu du champ Data envoyé dans le formulaire POST. Donnant la donnée data, mentionnée dans les exemples ci-dessous;
- Codage UTF-8 des données constituant le résultat de l’opération précédente
- 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(Data), UTF-8(secretKey))
Pour que le sceau soit calculé avec l'algorithme
HMAC-SHA-256, dont nous recommandons vivement l'utilisation, les
paramètres d'entrée de la requête doivent contenir le champ sealAlgorithm
avec la valeur suivante :
“HMAC-SHA-256”.
Exemples de code Hmac Sha256
- Exemple d’encodage Hmac Sha256 en Php 5
<?php … // Seal computation thanks to hash sorted data hash with merchant key $data_to_send= utf8_encode($data) $seal=hash_hmac('sha256', $data_to_send, $secretKey); … … ?>
data_to_send et secretKey doivent utiliser un jeu de caractères UTF-8. Référez-vous à la fonction utf8_encode pour la conversion de caractères ISO-8859-1 en UTF-8.
- Exemple d’encodage Hmac Sha256 en Java
import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class ExampleHMACSHA256 { /** * table to convert a nibble to a hex char. */ static final char[] hexChar = { '0' , '1' , '2' , '3' , '4' , '5' , '6' , '7' , '8' , '9' , 'a' , 'b' , 'c' , 'd' , 'e' , 'f'}; /** * Fast convert a byte array to a hex string * with possible leading zero. * @param b array of bytes to convert to string * @return hex representation, two chars per byte. */ public static String encodeHexString ( byte[] b ) { StringBuffer sb = new StringBuffer( b.length * 2 ); for ( int i=0; i<b.length; i++ ) { // look up high nibble char sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] ); // look up low nibble char sb.append( hexChar [b[i] & 0x0f] ); } return sb.toString(); } /** * Computes the seal * @param Data the parameters to cipher * @param secretKey the secret key to append to the parameters * @return hex representation of the seal, two chars per byte. */ public static String computeSeal(String data, String secretKey) throws Exception { Mac hmacSHA256 = Mac.getInstance("HmacSHA256"); SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"); hmacSHA256.init(keySpec); return encodeHexString(hmacSHA256.doFinal(data.getBytes())); } /** * @param args */ public static void main(String[] args) { try { System.out.println (computeSeal("parameters", "key")); } catch (Exception e) { e.printStackTrace(); } } }
- Exemple d’encodage Hmac Sha256 en .net
(Exemple effectué à l’aide d’un simple formulaire nommé « Form1 » contenant deux champs texte pour saisir data et txtSecretKey, ainsi qu’un autre champ pour afficher lblHEX).
using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Text; using System.Windows.Forms; using System.Security.Cryptography; namespace ExampleDotNET { public partial class Form1 : Form { public Form1() { InitializeComponent(); } private void cmdGO_Click(object sender, EventArgs e) { String sChaine = data.Text; UTF8Encoding utf8 = new UTF8Encoding(); Byte[] encodedBytes = utf8.GetBytes(sChaine); byte[] shaResult; HMAC hmac = new HMAC.Create("HMACSHA256"); var key = "YourSecretKey"; hmac.Key = utf8.GetBytes(key); hmac.Initialize(); shaResult = hmac.ComputeHash(encodedBytes); lblHEX.Text = ByteArrayToHEX(shaResult); } private string ByteArrayToHEX(byte[] ba) { StringBuilder hex = new StringBuilder(ba.Length * 2); foreach (byte b in ba) hex.AppendFormat("{0:x2}", b); return hex.ToString(); } } }
Validation du calcul de seal
Une fois votre calcul de seal mis en place, voici un exemple de requête vous permettant de vérifier que vous retrouvez bien le bon seal :
automaticResponseURL=https://automatic-response-url.fr/|normalReturnUrl=https://normal-return-url/|merchantId=011223344550000|keyVersion=1|merchantWalletId=wallet01|requestDateTime=2018-08-08T16:29:19.619+02:00|customerContact.email=customer@email.com
Pour la requête ci-dessus, avec algorithme de hachage HMAC-SHA-256 et une clé secrète valant :
secret123
Le seal attendu est :
406fa400c74ab8a2c4ad2801ec9d216991a8af4751059b3766157914cddf7912
Algorithme SHA-256
La valeur de la donnée Seal
est
calculée comme suit :
- 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 ) )
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();
}
}
}
Traiter les erreurs lors de l'initialisation de la gestion de wallet
Tous les champs reçus par Sips Walletpage POST à travers le connecteur font l’objet d’une vérification individuelle. Le tableau ci-dessous présente la liste des messages d’erreur pouvant s’afficher lors de cette étape ainsi que les solutions à mettre en œuvre.
Message | Cause | Solution |
---|---|---|
Unknown version interface: <version> | La valeur <version> dans le champ InterfaceVersion est inconnue. | Vérifier la version d’interface dans ce guide d’utilisation. |
Invalid keyword: <nomChamp>= <valeurChamp> | Le champ <nomChamp> n’est pas prévu dans la requête. | Vérifier le nom des champs dans le chapitre ci-dessous et dans le dictionnaire de données. |
Invalid field size: <nomChamp>= <valeurChamp> | Le champ <nomChamp> a une longueur incorrecte. | Vérifier la longueur du champ dans le dictionnaire de données. |
Invalid field value: <nomChamp >= <valeurChamp> | La valeur du champ <nomChamp> est incorrecte. | Vérifier les valeurs possibles du champ dans le dictionnaire de données. |
Mandatory field missing: <nomChamp > | Le champ <nomChamp> est manquant dans la requête. | Vérifier les champs obligatoires de la requête dans le chapitre ci-dessous. |
Unknown security version: <version> | La valeur <version> du champ keyVersion est inconnue. | Vérifier les versions des clés disponibles dans Sips Download. |
Invalid signature | La vérification du Seal de la requête a échoué. Cela peut être causé par un calcul incorrect de la donnée Seal ou peut indiquer la falsification de certains champs après le calcul de la signature. | Vérifier que le calcul du Seal est effectué comme indiqué dans le chapitre précédent. Si c’est le cas, demander un changement de clé secrète via Sips Download car la requête a été falsifiée. |
<Autres messages> | Dans le cas d’erreurs techniques, d’autres messages différents peuvent s’afficher. | Contacter le service d’assistance technique. |
Renseigner les champs de la requête
La requête et la réponse de la méthode walletManagementInit sont décrites sur cette page dédiée.
Paramétrer la requête de gestion du wallet
Voici un exemple de paramétrage de la requête de gestion du wallet pour chaque fonctionnalité disponible dans Sips Walletpage POST. Le détail de ces fonctionnalités est décrit dans le guide des fonctionnalités, le guide OneClick et le guide Subscription.
Restriction des fonctionnalités client de gestion de wallet
Par défaut, le client a accès à l’ensemble des fonctionnalités de gestion de wallet. Pour restreindre l’accès, il faut préciser la liste des fonctionnalités souhaitées dans le champ WalletActionNameList, comme ici pour ne permettre que d’ajouter ou modifier les moyens de paiement dans son wallet :
..| |walletActionNameList=ADDPM,UPDATEPM |..
Restriction dynamique des moyens de paiement
Il faut filtrer ceux qui seront disponibles pour être ajoutés dans le wallet grâce au champ paymentMeanBrandList :
..|paymentMeanBrandList=VISA,PAYPAL|..
Identification du wallet du client
L'identifiant du wallet du client doit être renseigné dans le champ merchantWalletId.
…|merchantWalletId=1205987|..
Prestataire agissant pour le compte d’un commerçant
Il faut passer l’identifiant du prestataire dans la requête dans le champ intermediateServiceProvider et utiliser la clé secrète de ce dernier pour calculer la donnée Seal :
..|intermediateServiceProviderId=241591|..
Traiter la réponse
Deux types de réponse sont prévus. Bien que les protocoles, formats et contenus des deux réponses soient exactement les mêmes, elles doivent être gérées de manière différente car elles répondent à deux besoins différents.
Les réponses sont des réponses HTTP(S) POST envoyées aux URL normalReturnUrl (obligatoire - réponse manuelle) et automaticResponseUrl (optionnelle - réponse automatique) précisées dans la requête.
Vous devez mettre en place le système permettant de décoder ces réponses, afin de connaître le résultat de requête.
Les quatre données suivantes sont définies dans les réponses :
Données | Notes/règles |
---|---|
Data | Concaténation des champs en réponse. |
Encode | Type d’encodage utilisé pour la donnée Data. Ce champ est valorisé avec le champ responseEncoding de la requête. |
Seal | Signature du message réponse. |
InterfaceVersion | Version de l’interface du connecteur. |
Si la valeur du champ Encode est “base64” ou “base64url”, la donnée Data doit-être décodée en Base64/Base64Url pour retrouver la chaîne des champs concaténée. La chaîne concaténée est structurée comme suit : clé1=valeur1|clé2=valeur2… Le sceau (donnée Seal) des 2 réponses est « hashé » avec le même algorithme utilisé en entrée et fourni dans le champ sealAlgorithm. Si aucune valeur n’a été définie, la valeur SHA-256 est utilisée par défaut.
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))
Exemple de Seal calculé avec une clé secrète égale à "secret123" et la donnée Data au format POST ci-dessous:
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 Seal que vous devez obtenir est c946655cce0059124b4ad3eb62c0922c51a0a7d8d28a3cf223e4c0da41bbc5b9
Exemple de Seal calculé avec une clé secrète égale à "secret123" et la donnée Data au format JSON ci-dessous:
{"keyVersion":1,"amount":44000,"captureDay":0,"captureMode":"AUTHOR_CAPTURE","currencyCode":"978","customerId":"40813","customerIpAddress":"213.118.246.190","merchantId":"225005049920001","orderAmount":44000,"orderChannel":"INTERNET","responseCode":"97","responseDescription":"Request time-out; transaction refused","transactionDateTime":"2023-03-15.00:39:04+0100","transactionReference":"dd88adfZ1027b40813f40813y1678837075","statementReference":"T7Ft4KKLRA2M11B9","s10TransactionId":"6","s10TransactionIdDate":"20230315","sealAlgorithm":"sha256","transactionPlatform":"PROD","paymentAttemptNumber":2,"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"}]}
Le Seal que vous devez obtenir est 77be1c230491c0d4eef6eaf910f635d42f55c90cd34c5a162c0ef6fcefb3f087
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 ) )
Exemple de Seal calculé avec une clé secrète égale à "secret123" et la donnée Data au format POST ci-dessous:
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 Seal que vous devez obtenir est 8fb7c5b7e972ed5a279629757aeae9885cdfc1fd888e6fc03114064e94bb2bf4
Exemple de Seal calculé avec une clé secrète égale à "secret123" et la donnée Data au format JSON ci-dessous:
{"keyVersion":1,"amount":44000,"captureDay":0,"captureMode":"AUTHOR_CAPTURE","currencyCode":"978","customerId":"40813","customerIpAddress":"213.118.246.190","merchantId":"225005049920001","orderAmount":44000,"orderChannel":"INTERNET","responseCode":"97","responseDescription":"Request time-out; transaction refused","transactionDateTime":"2023-03-15.00:39:04+0100","transactionReference":"dd88adfZ1027b40813f40813y1678837075","statementReference":"T7Ft4KKLRA2M11B9","s10TransactionId":"6","s10TransactionIdDate":"20230315","sealAlgorithm":"sha256","transactionPlatform":"PROD","paymentAttemptNumber":2,"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"}]}
Le Seal que vous devez obtenir est e9aa5be21186a9f9a417b82d1d450792851c849ccc8a2f85136897da29477975
Renseigner l’URL de la réponse manuelle
Le principal objectif de la réponse manuelle est de rediriger le client vers votre site web en indiquant le résultat de la gestion de wallet.
La page principale de Worldline Sips contient le bouton « Retour » avec un lien de redirection vers votre site. Lorsque le client clique sur ce bouton, le serveur Worldline Sips le redirige vers l’adresse URL contenue dans le champ normalReturnUrl fourni dans la requête. La redirection est une requête HTTP(S) POST qui contient les données de la réponse. Il est de votre responsabilité de récupérer ces paramètres et de vérifier la signature pour ainsi assurer l’intégrité des données de la réponse. De plus, vous avez pour responsabilité d’afficher à votre client les messages pertinents relatifs aux détails de la réponse.
Ce champ normalReturnUrl est également utilisé pour tous les résultats de paiement (annulation, refus...) afin de rediriger vers votre site.
Il est important de noter qu’il est impossible de garantir la réception de la réponse, celle-ci étant envoyée par le navigateur web du client. Tout d’abord, le client a la possibilité de ne pas cliquer sur le lien. Ensuite, la connexion qu’il utilise peut tout simplement avoir un problème et bloquer la transmission de cette réponse. Par conséquent, celle-ci ne peut pas constituer la base unique pour vos processus métier.
Renseigner l’URL de la réponse automatique
La réponse automatique est envoyée seulement si le champ automaticResponseUrl a été envoyé dans la requête de gestion du wallet. Si tel est le cas, le serveur Worldline Sips envoie une réponse HTTP(S) POST à l’adresse URL reçue.
Les champs de la réponse automatique sont identiques à ceux de la réponse manuelle. La seule différence entre les deux procédures est que la réponse automatique est envoyée directement par le serveur Worldline Sips sans passer par le navigateur Web du client. Par conséquent, elle est bien plus fiable car elle est toujours envoyée. Le serveur Worldline Sips n’attend aucune réponse après la transmission de la réponse automatique.
Il vous appartient de récupérer les différentes données de la réponse, vérifier la signature pour vous assurer de l’intégrité des champs de la réponse et, par conséquent, mettre à jour votre back office.
Choisir le format de la réponse : POST ou JSON
A partir de l'interfaceVersion
HP_3.0 Worldline 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
merchantId=029000254447216|keyVersion=1|merchantWalletId=2|merchantSessionId=null|customerId=null|customerIpAddress=10.78.106.17
|returnContext=null|walletCreationDateTime=2022-10-19T12:58:01+02:00|walletLastActionDateTime=2022-10-19T12:58:01+02:00
|walletPaymentMeanDataList={paymentMeanId=1, paymentMeanAlias=cb, paymentMeanBrand=CB, maskedPan=############0400, panExpiryDate=202301, mandateId=null, transactionActors=null, paymentMeanBrandSelectionStatus=NOT_APPLICABLE}
|customerCompanyName=null|customerBusinessName=null|customerLegalId=null|customerPositionOccupied=null
Le format JSON
Le format JSON a la structure suivante : { "clé1" : "valeur1", "clé2" : "valeur2", …}
Exemple d'une réponse en JSON
{
"keyVersion":1,"customerIpAddress":"10.78.106.17","merchantId":"029000254447216","merchantWalletId":"2","walletCreationDateTime":"2022-10-19.12:58:01+0200",
"walletLastActionDateTime":"2022-10-19.12:58:01+0200","sealAlgorithm":"sha256",
"walletPaymentMeanDataList":[
{"paymentMeanId":"1","paymentMeanAlias":"cb","paymentMeanBrand":"CB","maskedPan":"############0400","panExpiryDate":"202301","paymentMeanBrandSelectionStatus":"NOT_APPLICABLE"}
]
}
Comportement par défaut à partir de
l'interfaceVersion
HP_3.0
Le format de la réponse automatique et manuelle est déterminé par le connecteur qui a été utilisé lors des échanges HTTPS entre votre site Web et les serveurs de paiement Worldline Sips.
Interface Version | Connecteur | Format des réponses |
---|---|---|
WMR_WS_3.x | JSON | JSON (JS_3.x) |
HP_3.x | POST | POST (HP_3.x) |
WMR_WS_3.x | SOAP | POST (HP_3.x) |
Choisir les versions des réponses depuis la requête de management du wallet
Si vous souhaitez contourner ce comportement par défaut il est possible de renseigner depuis la requête les versions exactes des réponses automatiques et manuelles que vous utilisez.
Le champs de la requête de management du wallet qui permet de
renseigner la version de la réponse automatique est interfaceVersionAutomaticResponse
Le champs de la requête de management du wallet qui permet de
renseigner la version de la réponse manuelle est interfaceVersionNormalResponse
Ces deux nouveaux champs
interfaceVersionAutomaticResponse
et
interfaceVersionNormalResponse
sont facultatifs mais si
une des versions est renseignée l'autre devient obligatoire également.
Sinon la requête de management du wallet est en echec (code erreur
12).
Résoudre les problèmes de réception des réponses
Vous trouverez ci-dessous une liste des problèmes les plus couramment observés qui bloquent la réception des réponses automatiques et manuelles. Assurez-vous de les avoir vérifiés avant d’appeler le service d’assistance technique :
- vérifiez si les adresses URL de réponse sont fournies dans la requête de gestion du wallet et si elles sont valides. Pour faire cela, vous pouvez tout simplement les copier/coller dans votre navigateur ;
- les adresses URL fournies doivent être accessibles depuis l’extérieur, c'est-à-dire de l’Internet. Le contrôle d’accès (identifiant/mot de passe ou filtre IP) ou le pare-feu peuvent bloquer l’accès à votre serveur ;
- l’accès aux adresses URL de réponse doit être confirmé dans le journal des notifications de votre serveur Web ;
- si vous utilisez un port non standard, il doit être compris entre 80 et 9999 pour assurer la compatibilité avec Worldline Sips.
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.
Récupérer les champs des réponses
Le contenu des réponses Web automatiques et manuelles de Sips Walletpage est identique.
La liste des champs de la réponse est disponible sur cette page.
Analyser la réponse de gestion du wallet
Si vous procédez à une authentification par sceau électronique (seal), vous devez impérativement vérifier que le sceau reçu correspond bien au sceau que vous recalculez avec les champs de la réponse.
Si le sceau reçu ne correspond pas au sceau que vous recalculez, l’état de la session de gestion de wallet est considéré comme inconnu, veuillez contacter le support.
État | Champs de la réponse | Action à réaliser |
---|---|---|
Opération de gestion wallet prise en compte | walletLastActionDateTime renseigné avec la
date/heure courante walletPaymentMeanDataList contient les moyens de paiement du wallet après mise à jour |
Stockez dans votre base client les données suivantes du
wallet :
|
Opération de gestion wallet pas prise en compte | walletLastActionDateTime pas renseigné avec date/heure courante walletPaymentMeanDataList contient les moyens de paiement du wallet |
Si la mise jour wallet est requise alors resoumettez une requête. |
Étape 3 : tester sur l’environnement de simulation
Une fois le développement de la connexion à Sips Walletpage réalisé, vous pouvez effectuer un test sur le serveur Sips Walletpage de simulation.
URL de simu du serveur https://payment-webinit.simu.sips-services.com/walletManagementInit |
Pour effectuer ce test, il faut utiliser les identifiants en fonction du mode d’identification des transactions que vous souhaitez :
champ | Valeur |
---|---|
ID du commerçant (merchantId) | 002001000000001 |
Version de la clé (keyVersion) | 1 |
Clé secrète (secretKey) | 002001000000001_KEY1 |
champ | Valeur |
---|---|
ID du commerçant (merchantId) | 002001000000002 |
Version de la clé (keyVersion) | 1 |
Clé secrète (secretKey) | 002001000000002_KEY1 |
champ | Valeur |
---|---|
ID du commerçant (merchantId) | 002001000000003 |
Version de la clé (keyVersion) | 1 |
Clé secrète (secretKey) | 002001000000003_KEY1 |
champ | Valeur |
---|---|
ID du commerçant (merchantId) | 002001000000004 |
Version de la clé (keyVersion) | 1 |
Clé secrète (secretKey) | 002001000000004_KEY1 |
Tester l’ajout des cartes dans le wallet
Si vous souhaitez enregistrer une carte, vous êtes redirigé vers la page de saisie des informations de la carte où vous pouvez saisir les données détaillées de votre carte.
Les règles de simulation suivantes s’appliquent :
- le PAN doit comporter de 15 à 19 chiffres (selon le moyen de paiement utilisé) ;
- les six premiers chiffres du PAN déterminent le type de carte, conformément au tableau ci-dessous ;
Type de carte | Début du numéro de carte |
---|---|
AMEX | 340000 |
VPAY | 400000 |
VISA | 410000 |
CB | 420000 |
Cartes co-badgées CB et VISA | 430000 |
Cartes co-badgées CB et VPAY | 440000 |
Cartes co-badgées CB et VISA_ELECTRON | 450000 |
Cartes co-badgées VISA et MASTERCARD | 460000 |
MASTERCARD | 510000 |
MAESTRO | 500000 |
Cartes co-badgées CB et MASTERCARD | 520000 |
Cartes co-badgées CB et MAESTRO | 530000 |
- vous pouvez simuler la réussite ou l’échec de l’ajout d’une carte en faisant votre choix parmi tous les codes de réponse (cf. dictionnaire de données) et en modifiant les deux derniers chiffres. Seul le code réponse ‘00’ simule le succès de l’ajout.
Exemple : si vous utilisez le numéro de carte 4100 0000 0000 0005, la carte est identifiée comme VISA et l’ajout ne se fait pas (code réponse Worldline Sips 05).
Aussi, toutes les cartes sont enrôlées 3-D Secure, vous êtes redirigé vers le serveur de simulation 3-D Secure sur lequel vous choisissez le résultat désiré de l’authentification 3-D Secure.
Étape 4 : valider le passage en production
Une fois la connexion de votre site Web à Sips Walletpage POST testée, vous êtes à présent en mesure de valider la connexion à Sips Walletpage POST de production.
Au préalable, nous conseillons d’isoler votre site Web du public pour éviter que des clients ne génèrent des requêtes pendant cette phase de validation.
Si vous souhaitez personnaliser vos pages de paiement et de gestion de wallet, vous pouvez utiliser notre outil CustomPages, permettant de tester et visualiser le rendu des pages. Pour cela, merci de vous référer à la documentation CustomPages afin d’utiliser l’outil.
Pour basculer sur le serveur de production, vous devez changer l’URL pour vous connecter au serveur Worldline Sips de production en utilisant les identifiants merchantId, secretKey et keyVersion reçus lors l’inscription.
URL | https://payment-webinit.sips-services.com/walletManagementInit |
merchantId | Identifiant de la boutique reçu par mail |
SecretKey | Clé secrète que vous récupérez via l’extranet Sips Download |
keyVersion | Version clé secrète récupérée sur Sips Download (logiquement 1 pour la 1ère clé) |
Comment valider le bon fonctionnement en production
- Initiez un wallet en ajoutant une première carte dedans.
- Vérifiez que le wallet a bien été créé.
- Ajoutez une deuxième carte dans un wallet existant si l’option multicarte a été souscrite.
- Vérifiez que la 2e carte a bien été ajoutée.
Étape 5 : Démarrer en production
Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’ajouter des moyens de paiement dans leur wallet.