Introduction
Sogenactif 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 échelonné, …).
L’objectif du présent document est d’expliquer la mise en œuvre de la solution Sogenactif Office Server SOAP jusqu’au démarrage en production.
À qui s’adresse ce document
Ce document s’adresse aux commerçants qui souhaitent souscrire à l’offre Sogenactif et avoir recours à un connecteur à base d’échanges SOAP, 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 Sogenactif, nous vous conseillons de consulter les documents suivants :
- Présentation fonctionnelle
- Configuration des fonctionnalités
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 à Sogenactif Office Server SOAP.
Gestion de la clé secrète
Lors de votre inscription, SG met à disposition sur le Portail Sogenactif (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 Sogenactif.
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 Sogenactif Paypage, Sogenactif Office Serveur, Sogenactif In-App et Sogenactif Walletpage.
Contacter l'assistance
Pour toute question technique ou demande d'assistance, nos services sont disponibles du lundi au vendredi, hors jours fériés, de 9 h à 19 h :
- par téléphone au : +33 (0) 825 090 095 (0,15 € TTC/min + prix d’un appel local – Tarif au 12/09/2022)
- par e-mail : supportsogenactif@worldline.com
Pour faciliter le traitement de vos demandes, veuillez communiquer votre identifiant de commerçant : merchantId (numéro à 15 chiffres).
Comprendre le paiement avec Sogenactif Office Server SOAP
Le principe général d’un processus de paiement est le suivant :
1. Lorsque le client procède au paiement sur votre site, il doit saisir les informations du moyen de paiement.
2. Vous envoyez les informations relatives au paiement vers le serveur de paiement Sogenactif pour qu’il prenne en charge la transaction. Le serveur envoie une réponse pour que vous puissiez afficher le résultat du paiement.
3. Vous affichez le ticket contenant le résultat du paiement.
Démarrer avec Sogenactif Office Serveur en 6 étapes
Étape 1 : inscrire la boutique
Afin d’inscrire votre boutique, vous devez remplir le contrat Sogenactif envoyé par SG et le retourner à ce dernier.
Lors de la saisie du formulaire, vous désignez un contact administratif (qui accèdera à Sogenactif Gestion) et un contact technique (qui accèdera à Sogenactif Téléchargement) afin que SG puisse vous communiquer les informations nécessaires pour démarrer votre boutique.
SG procède alors à l’enregistrement de la boutique et vous retourne par e-mail votre identifiant commerçant (merchantId) ainsi que vos identifiants et les modalités de connexion au Portail Sogenactif et à Sogenactif Téléchargement.
Pour la connexion au Portail Sogenactif, le contact renseigné dans le contrat Sogenactif – rubrique « Portail Sogenactif » recevra un e-mail contenant l’identifiant et un lien pour générer lui-même son mot de passe. Pour la connexion à Sogenactif Téléchargement, le contact renseigné dans le contrat Sogenactif – rubrique « Sogenactif Téléchargement » recevra son mot de passe par e-mail, l’identifiant sera envoyé par mail séparé au contact renseigné pour le Portail Sogenactif.
Étape 2 : utiliser les fonctions disponibles
Les différentes fonctions possibles font l’objet de requêtes spécifiques. L'ensemble des fonctions disponibles avec sont listées sur cette page. En cliquant sur chaque fonction, vous pourrez voir le détails des champs en requête et en réponse, les urls et des exemples de requête et réponse.
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.
Une requête consiste en un appel vers un service Web SOAP situé sur la plateforme de paiement Sogenactif. Tous les champs nécessaires pour chaque requête doivent être fournis.
Syntaxe de la requête
La requête est construite conformément au format SOAP.
Exemple d’une requête de paiement d’un montant de 52,50 euros :
<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
<soapenv:Body>
<urn:paymentWebInit xmlns:urn='urn:sips:cn:contract:payment:v2'>
<urn:input>
<urn:amount>5250</urn:amount>
<urn:currencyCode>978</urn:currencyCode>
<urn:interfaceVersion> IR_WS_2.20</urn:interfaceVersion>
<urn:merchantId>011223744550001</urn:merchantId>
<urn:normalReturnUrl> http://www.normalreturnurl.com </urn:normalReturnUrl>
<urn:orderChannel>INTERNET</urn:orderChannel>
<urn:responseKeyVersion>1</urn:responseKeyVersion>
<urn:transactionReference>TREF0808151333</urn:transactionReference>
<urn:keyVersion>3</urn:keyVersion>
<urn:seal>3a02205859ffd2eff4d7dd015ce01fda11d80f03fa88e2caa188c5eea5a42c61</urn:seal></urn:input>
</urn:paymentWebInit>
</soapenv:Body>
</soapenv:Envelope>Présence des champs de la requête
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 Configuration des fonctionnalités pour savoir quels champs sont obligatoires ;
- dans certains cas d'usages (ex : paiement récurrent) ; veuillez consulter le Configuration des fonctionnalités pour savoir quels champs sont obligatoires.
Ces champs sont désignés avec la mention « conditionnel ».
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. Sogenactif 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 :
- 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))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”.
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 :
<cardOrder>
<input>
<amount>2500</amount>
<captureDay>0</captureDay>
<captureMode>AUTHOR_CAPTURE</captureMode>
<cardCSCValue>000</cardCSCValue>
<cardExpiryDate>201612</cardExpiryDate>
<cardNumber>1234123412341234</cardNumber>
<currencyCode>978</currencyCode>
<customerContact>
<email>customer@email.com</email>
</customerContact>
<interfaceVersion>IR_WS_2.3</interfaceVersion>
<keyVersion>1</keyVersion>
<merchantId>011223344550000</merchantId>
<orderChannel>INTERNET</orderChannel>
<orderId>ORD101</orderId>
<returnContext>ReturnContext</returnContext>
<transactionOrigin>SO_WEBAPPLI</transactionOrigin>
<transactionReference>TREFEXA2012</transactionReference>
<seal>f1772faa4b73c0fc5a9810ad7fcaf91458d6174b2178a0a0a2bea2d860b404f5</seal>
</input>
</cardOrder>Pour la requête ci-dessus, la chaîne concaténée que vous devez calculer est la suivante :
25000AUTHOR_CAPTURE0002016121234123412341234978customer@email.comIR_WS_2.3
011223344550000INTERNETORD101ReturnContextSO_WEBAPPLITREFEXA2012Avec un algorithme de hachage HMAC-SHA-256 et une clé secrète valant :
secret123Le seal attendu est :
f1772faa4b73c0fc5a9810ad7fcaf91458d6174b2178a0a0a2bea2d860b404f5Formulaire POST de redirection
Formulaire POST vers l'ACS
Votre site Web doit ordonner au navigateur du porteur de carte d'envoyer le formulaire comportant le message PaReq à l'URL ACS reçue dans le champ redirectionUrl du service cardCheckEnrollment ou walletCheckEnrollment. Cette action doit être initiée via le navigateur du porteur de carte.
Conformément aux directives de mise en œuvre de 3-D Secure édictées par VISA et Mastercard, cette action doit être réalisée en réduisant au minimum les interventions du porteur de carte.
Construction du formulaire de redirection
Votre site Web doit construire un formulaire POST pour rediriger l'utilisateur final vers l'ACS. Ce formulaire devra contenir les valeurs suivantes :
- le message PaReq : correspondant au champ paReqMessage renvoyé par le service cardCheckEnrollment ou walletCheckEnrollment.
- TermUrl : l’URL de votre site vers laquelle la réponse finale doit être envoyée après authentification de l’utilisateur final. Il doit s’agir d’une URL de votre site Web.
- le champ MD (« Merchant Data ») comporte des données sur le statut du commerçant qui doivent vous être retournées. Ce champ doit être utilisé pour récupérer la session sur votre site Web.
- Le formulaire doit comporter des en-têtes Content-Type et Content-Length.
Il est conseillé d'utiliser le langage JavaScript pour cette action mais ces implémentations doivent également fournir une solution alternative pour les navigateurs qui ne le gèrent pas, comme illustré dans l'exemple HTML ci-dessous.
Exemple de code de redirection HTTP POST - PAReq
<html>
<head>
<title>Title for Page</title>
</head>
<body OnLoad="OnLoadEvent();" >
<form name="downloadForm" action="ACS URL HERE(redirectionUrl)" method="POST">
<noscript>
<br>
<br>
<center>
<h1>Processing your 3-D Secure Transaction</h1>
<h2>JavaScript is currently disabled or is not supported by your browser.<br></h2>
<h3>Please click Submit to continue the processing of your 3-D Secure transaction.</h3>
<input type="submit" value="Submit">
</center>
</noscript>
<input type="hidden" name="PaReq" value="PAREQ HERE(paReqMessage)">
<input type="hidden" name="TermUrl" value="TERM URL HERE">
<input type="hidden" name="MD" value="MERCHANT DATA HERE">
</form>
<SCRIPT LANGUAGE="Javascript" >
<!--
function OnLoadEvent()
{
document.downloadForm.submit();
}
//-->
</SCRIPT>
</body>
</html>Authentification de l’utilisateur final
L'authentification de l'utilisateur final est gérée directement sur le serveur ACS. Par conséquent, vous ne pouvez avoir aucune influence sur cette authentification, ni sur l’aspect ou l’ergonomie de ces pages.
Redirection de l'utilisateur final vers votre site
À la fin du processus d'authentification, l'utilisateur final est redirigé vers votre site via une redirection HTTP.
L'ACS enverra avec cette URL, via POST, les résultats de l'authentification sous forme de variables. Les variables POST seront les suivantes :
| Champ | Commentaires |
|---|---|
| PaRes | Doit être spécifié dans le service cardValidateAuthentication |
| MD | Merchant Data comporte des données sur le statut du commerçant qui doivent vous être retournées. Ce champ doit être utilisé pour récupérer la session sur votre site Web. |
Formulaire POST vers des fournisseurs externes
Une fois l'initialisation traitée, votre site Web doit rediriger le navigateur du client à l’aide d’un formulaire POST.
Redirection HTTP POST
Votre site Web doit construire un formulaire de redirection pour rediriger le client vers le site Web externe, à l’aide de l’URL redirectionUrl fournie en réponse de la méthode d’initialisation.
Ce formulaire devra contenir les valeurs suivantes :
- message_version : messageVersion retourné lors de l’initialisation ;
- redirection_data : redirectionData retourné lors de l’initialisation ;
- le formulaire doit comporter des en-têtes Content-Type et Content-Length.
Il est conseillé d'utiliser le langage JavaScript pour cette action, mais ces implémentations doivent également fournir une solution alternative pour les navigateurs qui ne le gèrent pas, comme illustré dans l'exemple HTML ci-dessous.
Exemple de code de redirection HTTP POST
<html>
<head>
<title>Title for Page</title>
</head>
<body OnLoad="OnLoadEvent();">
<form name="downloadForm" action="REDIRECTION URL HERE (redirectionUrl)" method="POST">
<noscript>
<br>
<br>
<center>
<h1>Processing your Transaction</h1>
<h2>
JavaScript is currently disabled or is not supported by your
browser.
<br>
</h2>
<h3>Please click Submit to continue the processing of your transaction.</h3>
<input type="submit" value="Submit">
</center>
</noscript>
<input type="hidden" name="message_version" value="MESSAGE VERSION HERE (messageVersion)">
<input type="hidden" name="redirection_data" value="REDIRECTION DATA HERE (redirection_data)">
</form>
<SCRIPT LANGUAGE="Javascript">
function OnLoadEvent()
{
document.downloadForm.submit();
}
</SCRIPT>
</body>
</html>Données de sortie du formulaire POST
Au retour du site externe, le client est redirigé par un formulaire POST vers l’URL spécifiée dans le champ merchantReturnUrl de la méthode d’initialisation.
Vous devez récupérer les champs et les envoyer dans la requête de finalisation.
| Champ | Commentaires |
|---|---|
| merchantId | |
| messageVersion | |
| redirectionData |
Analyser les erreurs causées par une fonction
Le tableau ci-dessous vous donne les codes réponses génériques pour toutes les opérations. Veuillez consulter le dictionnaire des données pour connaître le détail des codes-réponse par fonction.
| État | Champs de la réponse | Action à réaliser |
|---|---|---|
| Fonction réalisée | responseCode = 00 | La fonction demandée a été réalisée avec succès (par exemple un remboursement avec la fonction refund). |
| Refus suite problème technique | responseCode = 90, 99 | Problème technique temporaire lors du traitement de la fonction. Essayez ultérieurement d’exécuter de nouveau la fonction. |
| Fonction non autorisée | responseCode = 40 | Vous n’avez pas les droits pour exécuter cette fonction. Prenez contact avec le centre d’assistance technique pour demander l’activation de ces droits si votre contrat acquéreur le permet. |
| Fonction non réalisée | Tout autre responseCode | La fonction n’a pas pu être réalisée car un des paramètres doit être incorrect. Consultez le dictionnaire des données pour connaître le détail de chaque code erreur et le format de chaque paramètre. |
Étape 3 : analyser la réponse de paiement
Si vous procédez à une authentification par sceau électronique (seal), vous devez impérativement vérifier que le sceau reçu correspond bien au sceau que vous recalculez avec les champs de la réponse.
Si le sceau reçu ne correspond pas au sceau que vous recalculez, l’état de la transaction est considéré comme inconnu : laissez la transaction en l’état, contactez le support et ne ré-exécutez pas la transaction de manière automatisée.
Étape 4 : tester sur l’environnement de recette client
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-sogenactif.test.sips-services.com
Pour effectuer ce test, il faut utiliser ces identifiants :
| ID du Commerçant | 201040040170001 |
| Version de la clé | 1 |
| Clé sécrète | rxSP61eeP_oNi5TxCD7Ngy9YcwC8MLw6OlmFGGcsY54 |
Le nom de chaque service a été présenté dans chaque fonction de l’étape 2.
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 la carte VISA suivante, pour simuler un paiement accepté :
| Cartes de test | cf page "Cartes de test" |
| Cryptogramme | 123 |
| Date de validité | doit être supérieure au mois en cours |
Étape 5 : valider le passage en production
Une fois la connexion de votre site et/ou application à Sogenactif Office Serveur testée, vous êtes à présent en mesure de valider la connexion à Sogenactif Office Serveur de production.
Au préalable, nous conseillons d’isoler votre site et/ou application du public pour éviter que des clients 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 Sogenactif de production en utilisant les identifiants reçus lors de l’inscription : merchantId, secretKey et keyVersion.
| URL Sogenactif | https://office-server.sogenactif.com |
| merchantId | Identifiant de la boutique reçu par e-mail |
| SecretKey | Clé secrète que vous récupérez Sogenactif Téléchargement |
| KeyVersion | Version clé secrète récupérée sur Sogenactif Téléchargement (logiquement 1 pour la 1ère clé) |
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 Sogenactif Gestion à 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 Sogenactif Gestion (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 6 : 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, 97, 99,
- fraude : responseCode 34,
- nombre max de tentatives de paiement atteint : responseCode 75.
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).
