• France
état des services
démonstrations
assistance
FAQContacter le support
Tutoriels vidéo
Rechercher
Catégories
Tags
Français
Français
Anglais
Accueil
Cas d'usage
Créer un paiement
Créer un paiement en plusieurs fois
Proposer un paiement complémentaire
Créer un paiement par alias (token)
Créer un lien de paiement
Créer un abonnement
Gérer vos abonnements
Gérer vos transactions (rembourser,...)
Analyser vos journaux
Docs API
Formulaire embarqué
API REST
Formulaire en redirection
Intégration mobile
Échange de fichiers
Exemples de code
Moyens de paiement
Modules de paiement
Guides
Back Office Marchand
Guides fonctionnels

Guide d'intégration (dépréciée)

Intégration dépréciée. Il est recommandé d'implémenter cette intégration : "Guide d'intégration".

Cette section décrit la manière d'implémenter les échanges entre le navigateur, le serveur marchand et la plateforme de paiement lorsque l'authentification du porteur est gérée par notre serveur d'authentification pendant la création du token.

Pour les marchands PCI-DSS ayant réalisé l'authentification du porteur via leur propre serveur d'authentification ou via le service PCI/Charge/Authenticate, consultez la section "Création d'un token avec authentification externe préalable".

1. Initier la demande de création du token

Appelez le Web Service PCI/Charge/CreateToken en utilisant les champs ci-dessous :

NIVEAU NOM DESCRIPTION REQUIS
1 currency Code (ISO 4217 alpha3) de la devise du paiement. Oui
1 orderId Référence de la commande. Non
1 customer Objet contenant les données de l'acheteur. Oui
2 email Adresse e-mail de l'acheteur. Oui
2 reference Référence de l'acheteur sur le site marchand.
Recommandé si vous souhaitez utiliser le wallet acheteur.
Non
1 paymentForms Objet contenant les données de la carte. Oui
2 paymentMethodType Type du moyen de paiement.
Doit être valorisé à CARD.
Oui
2 pan Numéro de carte. Oui
2 expiryMonth Mois d'expiration de la carte. Oui
2 expiryYear Année d'expiration de la carte. Oui
2 securityCode Code de sécurité de la carte (CVV ou 4DBC). Non
1 device Objet décrivant les informations du navigateur nécessaires à l'authentification du porteur. Oui
2 deviceType Type d'équipement sur lequel s'effectue le paiement.
Valeur possible :
  • BROWSER
Oui
2 acceptHeader Contenu exact du header HTTP "accept" tel qu'envoyé par le navigateur de l'acheteur. Oui
2 userAgent Contenu exact de l'entête HTTP "user-agent" envoyé par le navigateur.
Obtenue du navigateur client via la propriété navigator.userAgent.
Doit être tronqué si la valeur dépasse 2048 caractères.
Oui
2 ip Adresse IP (V4 ou V6) du navigateur telle que renvoyée dans les entêtes HTTP par le navigateur. Non
2 javaEnabled Booléen qui représente la capacité du navigateur à exécuter du Java.
Obtenue du navigateur client via la propriété navigator.javaEnabled().
Valeurs possibles :"true" ou "false".
Oui
2 language Chaîne de caractère indiquant la langue du navigateur.
Obtenue du navigateur client via la propriété navigator.language.
Exemples : "en", "en-US", "de", "fr".
Oui
2 colorDepth Valeur représentant la profondeur de la palette de couleurs utilisée par l'équipement pour afficher les images, en bits par pixel.
Obtenue du navigateur client via la propriété screen.colorDepth.
Oui
2 screenHeight La hauteur totale de l'écran de l'équipement en pixels.
Obtenue du navigateur client via la propriété screen.height.
Oui
2 screenWidth La largeur totale de l'écran de l'équipement en pixels.
Obtenue du navigateur client via la propriété screen.width.
Oui
2 timeZoneOffset Différence de temps entre le temps UTC et le temps local du navigateur client, en minutes.
Sa valeur est de -120 pour un utilisateur dans le fuseau horaire UTC+2 et de 570 pour le fuseau horaire UTC−09:30.
Oui

D'autres champs facultatifs sont disponibles. Retrouvez la description des champs dans notre playground.

Il est recommandé de transmettre un maximum de données sur l'acheteur via l'objet customer pour augmenter les chances d'obtenir une authentification frictionless.

Exemple de requête

/doc/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api-sogecommerce.societegenerale.eu/api-payment/V4/PCI/Charge/CreateToken
{

  "currency": "EUR", 
  "orderId":"myOrderId",
  "paymentForms": [
    {
      "paymentMethodType": "CARD",
      "pan": "4970100000000014",
      "brand": "VISA",
      "expiryMonth": "02",
      "expiryYear": "27",
      "securityCode": "123"
    }
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "device": {
    "deviceType": "BROWSER",
    "acceptHeader": "application/json",
    "ip": "89.249.65.28", 
    "javaEnabled": true,
    "language": "en",
    "colorDepth": "1",
    "screenHeight": 1024,
    "screenWidth": 768,
    "timezoneOffset": 0,
    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
  }
}
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

La suite du processus dépend de la présence d'un objet AuthenticationInstruction dans la réponse :

  • si la réponse contient un objet AuthenticationInstruction, vous devez traiter l'instruction pour procéder à l'authentification du porteur.
  • si la réponse contient un objet Payment, le processus est terminé.

2. Traitement des instructions

La réponse à l'appel au service PCI/Charge/CreateToken contient un objet AuthenticationInstruction :

  • si la réponse contient une instruction CHALLENGE, vous créez une iFrame **visible** pour afficher la page d'authentification.
  • si la réponse contient une instruction FINGERPRINT, vous créez une iFrame **invisible** pour afficher la page d'exécution du code JavaScript de l'ACS.

2.1. Création de l'iFrame

Quel que soit le type d'instruction reçue (CHALLENGE ou FINGERPRINT), vous devez construire une iFrame en utilisant les données reçues dans l'objet target.

Exemples de données transmises en fonction du type d'instruction

Instruction "CHALLENGE"

"target":{
  "element":"IFRAME",
  "visible":true,
  "width":500,
  "height":600,
  "_type":"V4/Charge/Authenticate/InstructionTarget"
}

Instruction "FINGERPRINT"

(3DS Method)

"target":{
  "element":"IFRAME",
  "visible":false,
  "_type":"V4/Charge/Authenticate/InstructionTarget"
}

2.2. Soumission du formulaire de demande d'authentification

Une fois l'iFrame créée, utilisez les données reçues dans l'objet http pour permettre :

  • soit l'affichage de la page d'authentification de l'émetteur du moyen de paiement, pour une instruction de type CHALLENGE,
  • soit l'exécution du code JavaScript de l'ACS de l'émetteur de moyen de paiement, pour une instruction de type FINGERPRINT.

Exemples de données transmises dans l'objet http :

Challenge 3DS2

"http":{
  "method":"POST",
  "url":"https://acs.sg.com/v2/creq",
  "body":{
    "creq":"eyJ0aHJlZURTU2Vy...",
    "threeDSSessionData":"H4sIAAAAAAAAAC2OyZK..."
  },
  "_type":"V4/Charge/Authenticate/HttpRequest"
},

Fingerprint

"http":{
  "method":"POST",
  "url":"https://acs.sg.com/v2/3dsMethod",
  "body":{
    "threeDSMethodData":"eyJ0aHJlZURzTW..."
  },									
  "_type":"V4/Charge/Authenticate/HttpRequest"
},

Exemple d'implémentation JavaScript

    function createInstructionIframe(instruction) {
        // Get instruction container element
        container = document.getElementById('instructionContainer');

        // Clean instruction container
        container.innerHTML = '';

        // Create iframe element
        var iframe = document.createElement('iframe');
        iframe.id = 'instructionIframe';
        iframe.name = 'instructionIframe';
        iframe.src = 'about:blank';
        iframe.style.width = instruction.value.target.width+"px";
        iframe.style.height = instruction.value.target.height+"px";
        iframe.style.visibility = instruction.value.target.visible ? 'visible' : 'hidden';

        // Handle timeout
        if(instruction.value.timeout){
            setTimeout(() => {
                const instructionResultTimeout = {
                    eventName: 'LYRA_AUTH_INSTRUCTION_RESULT',
                    value: {
                        name: instruction.value.name,
                        value: 'TIMEOUT',
                        protocol: {
                            name: instruction.protocol.name,
                            version: instruction.protocol.version,
                            network: instruction.protocol.network,
                            challengePreference: instruction.protocol.challengePreference,
                            simulation: instruction.protocol.simulation
                        },
                    },
                };
                window.postMessage(JSON.stringify(instructionResultTimeout), '*');
            }, instruction.value.timeout * 1000);
        }

        // Add iframe to container
        container.appendChild(iframe);

        // Create form to post
        var form = document.createElement('form');
        form.id = 'instructionForm';
        form.name = 'instructionForm';
        form.target = 'instructionIframe';
        form.method = instruction.value.http.method;
        form.action = instruction.value.http.url;
        form.style = 'visibility: hidden';

        // Create form body
        Object.keys(instruction.value.http.body).forEach(function (name) {
            form.innerHTML += '<input name="' + name + '" value="' + instruction.value.http.body[name] + '">';
        });
        var body = document.createElement('form');

        // Add form to container
        container.appendChild(form);

        // Triger form submit
        form.submit();
    }

Il est impératif de sauvegarder le champ operationSessionId contenu dans la réponse. Ce paramètre est requis pour la suite de l'authentification.

Exemple d'appel de la fonction createInstructionIframe en PHP

//Call the PCI/Charge/CreateToken method
$obj = pcicreatetoken($data);
if ($obj['answer']['_type']== 'V4/AuthenticationResponseData'){ 
	$response= $obj['answer'];
	
	//Test if anwser contains an instruction
	if($response['value']['_type'] == 'V4/Charge/Authenticate/AuthenticationInstruction'){		
		$_SESSION['operationSessionId'] = $response['operationSessionId'];
		
		//create an iFrame to proceed to the payer authentication						
		echo '<script>window.onload = function(){ var instruction =JSON.parse(\''. json_encode($response) .'\'); createInstructionIframe(instruction);}</script>';
	}	
}

3. Mise en place d'un listener d'événement

Après authentification du porteur du moyen de paiement ou après exécution du 3DS Method, le navigateur du client transmet une réponse sous forme d'événement JavaScript.

Utilisez le code suivant pour capter l'événement :

window.addEventListener('message', function (messageEvent) {
    
    var data = messageEvent.data;
    try {
        var messageData = JSON.parse(data);
        if (messageData.eventName === 'LYRA_AUTH_INSTRUCTION_RESULT') {
            try {
                // callback call with messageData.value content
                container = document.getElementById('instructionContainer');
                var form = document.createElement('form');
                
                form.method = 'POST';
                form.action = "https://myhost.com/payment/authentication/result.php";
                form.style = 'visibility: hidden';					
                    
                form.innerHTML += "<input name='messageData' value='" + data + "'>";  
                                
                var body = document.createElement('form');
                
                container.appendChild(form);
                form.submit();
            } catch (err) {
                // error callback call
            } finally {
                // always close the iFrame/popin
                container = document.getElementById('instructionContainer');
                container.remove();
            }
        }
    } catch (err) {
        // process eventual exceptions during callbacks
    }
    
}, false);

Remplacez la valeur de "form.action", dans le code ci-dessus, avec l'URL de votre page de retour.

Exemples d'événements "LYRA_AUTH_INSTRUCTION_RESULT"

après une authentification Challenge 3DS2

{
  "eventName":"LYRA_AUTH_INSTRUCTION_RESULT",
  "value":{
    "name":"CHALLENGE",
    "value":"eyJjZXJ0aWZpY2F0ZSI...",
    "protocol":{
      "name":"THREEDS",
      "version":"2.1.0",
      "network":"VISA",
      "challengePreference":"NO_PREFERENCE",
      "simulation":true
    }
  }
}

après exécution du code 3DS Method de l'ACS (authentification 3DS2)

{
  "eventName":"LYRA_AUTH_INSTRUCTION_RESULT",
  "value":{
    "name":"FINGERPRINT",
    "value":"eyJjZXJ0aWZpY2F0Z...",
    "protocol":{
      "name":"THREEDS",
      "version":"2.1.0",
      "network":"VISA",
      "challengePreference":"NO_PREFERENCE",
      "simulation":true
    }
  }
}

en cas de timeout durant un challenge (3DS2)

{
  "eventName":"LYRA_AUTH_INSTRUCTION_RESULT",
  "value":{
    "name":"CHALLENGE",
    "value":"TIMEOUT",
    "protocol":{
      "name":"THREEDS",
      "version":"2.1.0",
      "network":"VISA",
      "challengePreference":"NO_PREFERENCE",
      "simulation":true
    }
  }
}

4. Gestion des événements "LYRA_AUTH_INSTRUCTION_RESULT"

Lorsqu'un événement LYRA_AUTH_INSTRUCTION_RESULT est reçu, appelez le Web Service PCI/Charge/CreateToken afin de décoder son contenu.

Utilisez les champs suivants dans votre requête :

NOM DESCRIPTION requis
operationSessionId Identifiant de la requête d'authentification fourni dans la réponse à l'appel initial. Oui
instructionResult Objet contenant le détail de l'instruction reçu dans l'événement JavaScript "LYRA_AUTH_INSTRUCTION_RESULT". Oui

Exemple de requête

/doc/fr-FR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api-sogecommerce.societegenerale.eu/api-payment/V4/PCI/Charge/CreateToken
{
  "instructionResult": {
    "name" : "CHALLENGE",
    "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "protocol" : {
      "name" : "THREEDS",
      "network": "VISA",
      "version" : "2.0.2",
      "challengePreference": "NO_PREFERENCE",
      "simulation": false
    }
  },
  "operationSessionId": "c7f9c8711d994aa5818f886dc995e9eb"
}
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

La suite du processus dépend de la présence d'un objet AuthenticationInstruction dans la réponse :

* La réponse contient un objet AuthenticationInstruction : vous devez traiter l'instruction pour continuer le processus d'authentification du porteur. * La réponse contient un objet Payment : le procesus est terminé.

5. URL de notification à la fin du paiement

A la fin de l'opération, vous recevrez une IPN uniquement si la réponse à l'appel initial est de type AuthenticationInstruction.

Lorsque la réponse à l'appel initial est de type Payment, il vous suffit d'analyser son contenu pour obtenir le résultat de la création de l'alias.

C'est le cas notamment :

  • lorsque la carte ou le marchand n'est pas enrôlé 3D Secure,
  • si vous avez désactivé l'authentification du porteur,
  • si l'authentification du porteur se fait sans interaction et sans 3DS Method.

Pour plus d'informations sur le fonctionnement ou la configuration des règles de notification, consultez le chapitre Analyse de l'IPN (URL de notification).

6. Analyse du résultat

La réponse contient un objet Payment décrivant le détail de l'alias et de la vérification du moyen de paiement (résultat de la demande de vérification, résultat de l'authentification du porteur, etc...).

L'identifiant unique du token est retourné dans le champ paymentMethodToken.

Consultez la description de l'objet Payment depuis notre playground.

7. Tests et cas d'utilisation

Pour vous aider à intégrer le service, consultez la section Tests et cas d'utilisation (dépréciée) qui présente les différents échanges entre votre serveur, le navigateur et la plateforme de paiement.

© 2025 Tous droits réservés à Sogecommerce
25.22-1.11