Office Serveur JSON

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

Faire un retour sur cette page

La dernière interfaceVersion est 2.55.

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

A 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 JSON via le protocole REST, en mode machine à machine.

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

Pour avoir une vue d’ensemble de la solution 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 JSON.

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

IMPORTANT: en cas de compromission d’une clé secrète, vous êtes tenu d’en demander au plus vite la révocation puis le renouvellement via le Portail Sogenactif (voir la « notice de renouvellement des clés secrètes »).

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

IMPORTANT: une clé secrète est associée à une version. Après avoir obtenu une nouvelle clé secrète, vous devez impérativement modifier votre requête et indiquer la nouvelle version dans le champ keyVersion, sans quoi vous obtiendrez un code réponse 34 (suspicion de fraude).

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 JSON

Le principe général d’un processus de paiement est le suivant :

image du principe général d’un processus de paiement

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.

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

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

Tip: avant d’utiliser une fonction, vérifiez que vous avez bien les droits pour utiliser cette fonction sur votre boutique en contactant l’assistance technique Sogenactif.

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 REST (JSON) situé sur la plateforme de paiement Sogenactif. Tous les champs nécessaires pour chaque requête doivent être fournis.

Attention: pour rappel, il est nécessaire d'indiquer, dans l'en-tête de votre message, que les données à traiter sont de type JSON. Vous devez pour cela préciser l'en-tête 'Content-Type: application/json' dans votre message JSON. À défaut vous risquez de recevoir un message d'erreur de ce type :

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html>
    <head>
        <title>415 Unsupported Media Type</title>
    </head>
    <body>
        <h1>Unsupported Media Type</h1>
        <p>The supplied request data is not in a format
acceptable for processing by this resource.</p>
    </body>
</html>

Tip: dans les réponses, en fonction de l’état de la transaction et du moyen de paiement choisi, certains champs peuvent être nuls, vides ou non renseignés. Veuillez consulter les documentations des moyens de paiement pour connaître les champs attendus dans les réponses.

Syntaxe de la requête

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

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

Exemple d’une requête cardOrder:

{
  "amount": "2500",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "0000",
  "cardExpiryDate": "201612",
  "cardNumber": "1234123412341234",
  "currencyCode": "978",
  "interfaceVersion": "IR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": " ORD101",
  "returnContext": "ReturnContext",
  "transactionOrigin": "SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "2205f0636dc500c4f3ef536075895b8baba3a60c7087e06cd9d330c50a50c53e"
}

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

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

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

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

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

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

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

Exemple d’une requête cardOrder avec une liste d’objets complexes pour le champ shoppingCartDetail contenant deux produits nommés productName1 et productName2 :

{
  "amount": "1000",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "100",
  "cardExpiryDate": "202305",
  "cardNumber": "5017670000000000",
  "currencyCode": "978",
  "customerId": "customerId1",
  "customerIpAddress": "127.0.0.1",
  "interfaceVersion": "IR_WS_2.49",
  "keyVersion": "1",
  "merchantId": "201040040170001",
  "merchantTransactionDateTime": "2023-04-05T10:01:56.520+02:00",
  "orderChannel": "INTERNET",
  "orderId": "123",
  "panType": "PAN",
  "paymentPattern": "ONE_SHOT",
  "returnContext": "Mon contexte de retour",
  "sealAlgorithm": "SHA-256",
  "shoppingCartDetail": {
    "shoppingCartItemList": [
      {
        "productCategory": "Physical",
        "productCode": "CodeProd1",
        "productDescription": "Prod_Description1",
        "productName": "productName1",
        "productQuantity": "2",
        "productSKU": "productSKU1",
        "productTaxRate": "0",
        "productUnitAmount": "10",
        "productUnitTaxAmount": "240"
      },
      {
        "productCategory": "Physical",
        "productCode": "CodeProd2",
        "productDescription": "Prod_Description2",
        "productName": "productName2",
        "productQuantity": "2",
        "productSKU": "productSKU2",
        "productTaxRate": "0",
        "productUnitAmount": "10",
        "productUnitTaxAmount": "240"
      }
    ],
    "shoppingCartTotalAmount": "40",
    "shoppingCartTotalTaxAmount": "960"
  },
  "transactionOrigin": "SIPS-SIM",
  "transactionReference": "SIM20230405100157",
  "seal": "44bab6daa67af2f6c91b40f08a428c66c151f80627ba2f905376b17a3d4c535c"
}

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.

IMPORTANT: si votre clé secrète est compromise, ou si vous supposez que c’est le cas, vous devez impérativement demander son renouvellement en vous connectant à Sogenactif Téléchargement.

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

Attention: par défaut, le sceau est calculé avec l'algorithme HMAC-SHA-256, dont nous recommandons vivement l'utilisation.

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

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 :

{
  "amount": "2500",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "000",
  "cardExpiryDate": "201612",
  "cardNumber": "1234123412341234",
  "currencyCode": "978",
  "customerContact":{
    "email":"customer@email.com"
  },
  "interfaceVersion": "IR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "ORD101",
  "returnContext": "ReturnContext",
  "transactionOrigin": "SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "f1772faa4b73c0fc5a9810ad7fcaf91458d6174b2178a0a0a2bea2d860b404f5"
}

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_WEBAPPLITREFEXA2012

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

secret123

Le seal attendu est :

f1772faa4b73c0fc5a9810ad7fcaf91458d6174b2178a0a0a2bea2d860b404f5

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

IMPORTANT: le champ MD doit contenir uniquement des caractères ASCII compris entre 0x20 et 0x7E; si d'autres données sont nécessaires, le champ doit être encodé en Base64. La taille du champ (après le codage Base64, le cas échéant) est limitée à 1024 octets. Si des données confidentielles sont incluses (telles que le PAN), elles doivent être cryptées.

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.

Attention: veillez à bien remplacer le début de l’URL de production fournie dans chaque fonction par celui de l'URL de recette indiquée ci-dessus.

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

Attention: la boutique de test est configurée en "mode transactionReference", sans génération automatique du transactionReference. Par conséquent, il est nécessaire que vous transmettiez le champ transactionRefence valorisé dans vos requêtes de test.

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

Attention: une erreur fréquente est d’oublier un de ces 4 paramètres, ce qui conduit systématiquement à une erreur.

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