• France
Back Office Marchand
assistance
FAQContacter le support
Rechercher
Catégories
Tags
Français
Français
Anglais
Accueil
Cas d'usage
Créer un paiement
Créer un paiement en plusieurs fois
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 (mode expert)

Ce guide est destiné aux marchands PCI-DSS utilisant notre API pour réaliser les authentifications en mode e-commerce (porteur présent).

Si vous souhaitez implémenter les authentifications 3RI (porteur non présent), consultez la page : 3RI - Requestor-Initiated Authentication.

1. Initier une demande d'authentification du porteur

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

NOM DESCRIPTION
amount entier | Longueur : 1-12 | requis

Montant de la transaction exprimé dans la plus petite fraction de la devise (par exemple : 30050 pour 30050 XPF).
currency chaine | Longueur : 3 | requis

Code de la devise selon la norme ISO 4217 alpha-3 (par exemple : "XPF" pour le franc CFP).
Valeurs possibles
Devise CODIFICATION ISO 4217 Unité fractionnaire
Dollar australien (036)AUD 2
Renminbi yuan chinois (156)CNY 1
Franc Djibouti (262)DJF 0
Euro (978)EUR 2
Dollar de Fidji (242)FJD 2
Livre Sterling (826)GBP 2
Dollar de Hong Kong (344)HKD 2
Yen (392)JPY 0
Riel Cambodgien (116)KHR 0
Kip laotien (418)LAK 0
Dollar néo-zélandais (554)NZD 2
Dollar des Îles Salomon (090)SBD 2
Baht thailandais (764)THB 2
Dollar des États-Unis (840)USD 2
Vatu des Îles Vanuatu (548)VUV 0
Franc CFP (953)XPF 0
productType énumération | optionnel

Type de produit concerné par la transaction.
Valeurs possibles
Valeur Description
ACCOUNT_FUNDING Versement sur un compte
CHECK_ACCEPTANCE Vérification d'acceptation
GOODS_OR_SERVICE_PURCHASE Achat de bien ou de service. Valeur utilisée par défaut.
PREPAID_ACTIVATION_AND_LOAD Activation et charge d'une carte prépayée
QUASI_CASH_TRANSACTION Transactions en quasi-espèces (ex : chèque vacances, billet de loterie, etc.)
transactionCategory énumération | requis

Catégorie de la transaction. Doit être valorisé à PAYMENT.
transactionInitiator énumération | optionnel

Initiateur de la transaction. Doit être valorisé à CUSTOMER.
paymentSource énumération | optionnel

Source du paiement. Doit être valorisé à EC.
customer objet JSON | recommandé

Objet contenant les informations sur l'acheteur.
Détails de l'objet
NOM DESCRIPTION
reference chaine | Longueur : 0-80 | optionnel

Identifiant de l'acheteur chez le marchand.
email chaine | Longueur : 0-150 | recommandé

Adresse e-mail
accountDetails objet JSON | recommandé

Objet contenant les informations du compte de l'acheteur sur le site marchand.
Détails de l'objet
NOM DESCRIPTION
authenticationMethod énumération | recommandé

Méthode d'authentification de l'acheteur sur le site marchand.
Valeurs possibles
Valeur Description
GUEST Pas d'authentification (invité).
PERSONAL_CREDENTIALS Utilisation d'un compte créé sur le site marchand.
FEDERATED_CREDENTIALS Utilisation de l'authentification fédérée.
ISSUER_CREDENTIALS Utilisation d'identifiants fournis par l'émetteur.
EXTERNAL_CREDENTIALS Authentification par un tiers.
FIDO_CREDENTIALS Utilisation de l'authentification FIDO (Fast IDentity Online).
billingDetails objet JSON | optionnel

Objet contenant les informations sur l'acheteur.
Détails de l'objet
NOM DESCRIPTION
title chaine | Longueur : 0-63 | optionnel

Civilité de l'acheteur.
Exemples de valeurs
  • Mr
  • M.
  • Mme
category énumération | optionnel

Type de client.
Valeurs possibles
Valeur Description
PRIVATE Client de type Particulier.
COMPANY Client de type Société.
firstName chaine | Longueur : 0-63 | optionnel

Prénom.
lastName chaine | Longueur : 0-63 | optionnel

Nom.
phonenumber chaine | Longueur : 0-32 | optionnel

Numéro de téléphone fixe.
Exemples de valeurs
  • 0123456789
  • +33123456789
  • 0033123456789
  • (00.571) 638.14.00
  • 40 41 42 42
streetNumber chaine | Longueur : 0-64 | optionnel

Numéro de rue.
address chaine | Longueur : 0-255 | optionnel

Adresse de facturation.
address2 chaine | Longueur : 0-255 | optionnel

Informations complémentaires sur l'adresse.
district chaine | Longueur : 0-127 | optionnel

Quartier.
zipCode chaine | Longueur : 0-64 | optionnel

Code postal.
city chaine | Longueur : 0-128 | optionnel

Ville.
state chaine | Longueur : 0-127 | optionnel

Région.
country chaine | Longueur : 2 | optionnel

Code pays (norme ISO 3166-1 alpha-2).
Exemples de valeurs
Valeur Description
AT AUTRICHE
BE BELGIQUE
FR CORSE
CI COTE D'IVOIRE
FR FRANCE
GP GUADELOUPE
MQ MARTINIQUE
NC NOUVELLE-CALÉDONIE
PM ST-PIERRE-ET-MIQUELON
PF POLYNESIE FRANCAISE
language chaine | Longueur : 2 | optionnel

Code langue (norme ISO 639-1).
Exemples de valeurs
Valeur Description
DE Allemand (Allemagne)
EN Anglais (Royaume Uni)
EN Anglais (Etats-Unis )
ZH Chinois (Traditionnel)
ES Espagnol (Espagne)
ES Espagnol (Chili)
FR Français (France)
IT Italien (Italie)
JP Japonais (Japon)
NL Néerlandais (Pays-Bas)
PL Polonais (Pologne)
PT Portugais (Brésil)
PT Portugais (Portugal)
RU Russe (Russie)
cellPhonenumber chaine | Longueur : 0-32 | optionnel

Numéro de téléphone mobile.
Exemples de valeurs
  • 0623456789
  • +33623456789
  • 0033623456789
  • (+34) 824 65 43 21
  • 87 77 12 34
identityCode chaine | Longueur : 0-150 | optionnel

Identifiant national.
identityType chaine | Longueur : 0-3 | optionnel

Type de pièce d'identité.
Valeurs possibles
Pays Type Description
Argentina DNI Documento Nacional de Identidad.
Brasil CNPJ Cadastro Nacional da Pessoa Jurídica.
CPF Cadastro de Pessoas Físicas.
Colombia CC Cédula de ciudadania.
TI Tarjeta de Identidad.
CE Cédula de Extranjeria.
NI Número de Identificación Tributaria.
PS Pasaporte.
Peru DNI_PER Documento National de Identidad.
PAR Partida de Nacimiento.
PAS Pasaporte.
LMI Libreta Militar.
NAN Otro.
legalName chaine | Longueur : 0-100 | optionnel

Raison Sociale.
shippingDetails objet JSON | optionnel

Objet contenant les informations de livraison.
Détails de l'objet
NOM DESCRIPTION
category énumération | optionnel

Type de client.
Valeurs possibles
Valeur Description
PRIVATE Client de type Particulier.
COMPANY Client de type Société.
firstName chaine | Longueur : 0-63 | optionnel

Prénom.
lastName chaine | Longueur : 0-63 | optionnel

Nom.
phonenumber chaine | Longueur : 0-32 | optionnel

Numéro de téléphone fixe.
Exemples de valeurs
  • 0123456789
  • +33123456789
  • 0033123456789
  • (00.571) 638.14.00
  • 40 41 42 42
streetNumber chaine | Longueur : 0-64 | optionnel

Numéro de rue.
address chaine | Longueur : 0-255 | optionnel

Adresse de livraison.
address2 chaine | Longueur : 0-255 | optionnel

Informations complémentaires sur l'adresse de livraison.
district chaine | Longueur : 0-127 | optionnel

Quartier.
zipCode chaine | Longueur : 0-64 | optionnel

Code postal.
city chaine | Longueur : 0-128 | optionnel

Ville.
state chaine | Longueur : 0-127 | optionnel

Région.
country chaine | Longueur : 2 | optionnel

Code pays (norme ISO 3166-1 alpha-2).
Exemples de valeurs
Valeur Description
AT AUTRICHE
BE BELGIQUE
FR CORSE
CI COTE D'IVOIRE
FR FRANCE
GP GUADELOUPE
MQ MARTINIQUE
NC NOUVELLE-CALÉDONIE
PM ST-PIERRE-ET-MIQUELON
PF POLYNESIE FRANCAISE
deliveryCompanyName chaine | Longueur : 0-127 | optionnel

Nom de la société de livraison.
shippingSpeed énumération | optionnel

Délai de livraison.
Valeurs possibles
Valeur Description
STANDARD Livraison standard.
EXPRESS Livraison en moins de 24h.
PRIORITY Livraison Prioritaire (Click & Collect).
shippingMethod énumération | optionnel

Mode de livraison.
Valeurs possibles
Valeur Description
RECLAIM_IN_SHOP Retrait de marchandise en magasin.
RELAY_POINT Utilisation d'un réseau de points de retrait tiers (Kiala, Alveol, etc).
RECLAIM_IN_STATION Retrait dans un aéroport, une gare ou une agence de voyage.
PACKAGE_DELIVERY_COMPANY Livraison par transporteur (Colissimo, UPS, etc).
ETICKET Emission d'un billet électronique, téléchargement de produit virtuel.

Valeurs réservées à un usage futur :
Valeur Description
CARD_HOLDER_ADDRESS Livraison chez l'acheteur.
VERIFIED_ADDRESS Livraison à une adresse vérifiée.
NOT_VERIFIED_ADDRESS Livraison à une adresse non vérifiée.
SHIP_TO_STORE Livraison en magasin.
DIGITAL_GOOD Livraison digitale.
ETRAVEL_OR_ETICKET Billet électronique.
OTHER Autre.
PICKUP_POINT Retrait en point relais.
AUTOMATED_PICKUP_POINT Retrait en point relais automatique.
identityCode chaine | Longueur : 0-150 | optionnel

Identifiant national.
legalName chaine | Longueur : 0-100 | optionnel

Raison Sociale.
shoppingCart objet JSON | optionnel

Objet contenant les informations sur le panier.
Détails de l'objet
NOM DESCRIPTION
insuranceAmount entier | Longueur : 1-12 | optionnel

Montant de l'assurance pour l'ensemble de la commande, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
shippingAmount entier | Longueur : 1-12 | optionnel

Montant des frais de livraison pour l'ensemble de la commande, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
taxAmount entier | Longueur : 1-12 | optionnel

Montant des taxes pour l'ensemble de la commande, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
cartItemInfo tableau | optionnel

Liste d'objets Customer/ShoppingCartItem contenant les informations sur chaque article du panier.
Détails de l'objet
NOM DESCRIPTION
productLabel chaine | Longueur : 0-255 | optionnel

Nom du produit.
productType énumération | optionnel

Type de produit.
Valeurs possibles
Valeur Description
FOOD_AND_GROCERY Produits alimentaires et d'épicerie.
AUTOMOTIVE Automobile / Moto.
ENTERTAINMENT Divertissement / Culture.
HOME_AND_GARDEN Maison et jardin.
HOME_APPLIANCE Équipement de la maison.
AUCTION_AND_GROUP_BUYING Ventes aux enchères et achats groupés.
FLOWERS_AND_GIFTS Fleurs et cadeaux.
COMPUTER_AND_SOFTWARE Ordinateurs et logiciels.
HEALTH_AND_BEAUTY Santé et beauté.
SERVICE_FOR_INDIVIDUAL Services à la personne.
SERVICE_FOR_BUSINESS Services aux entreprises.
SPORTS Sports.
CLOTHING_AND_ACCESSORIES Vêtements et accessoires.
TRAVEL Voyage.
HOME_AUDIO_PHOTO_VIDEO Son, image et vidéo.
TELEPHONY Téléphonie.
productRef chaine | Longueur : 0-64 | optionnel

Référence du produit.
productQty entier | Longueur : 1-12 | optionnel

Quantité du produit.
productAmount entier | Longueur : 1-12 | optionnel

Montant du produit, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
productVat chaine | Longueur : 1-12 | optionnel

Montant de la taxe sur le produit.
Type de valeurs possibles
  • Un nombre entier

    Pour exprimer un montant en centime appliqué sur le produit concerné.

  • Un nombre décimal

    Pour exprimer un pourcentage appliqué sur le montant du produit concerné avec maximum 4 chiffres après la virgule.

    La décimale est obligatoire pour exprimer un pourcentage. La décimale est marquée par le caractère ".".

previousAuthentication objet JSON | ignoré

Objet contenant les données de l'authentification précédente.
device objet JSON | requis

Objet contenant les informations sur le navigateur.
Détails de l'objet
NOM DESCRIPTION
deviceType énumération | requis

Type d'appareil sur lequel s'effectue l'authentification.
Valeurs possibles
Valeur Description
BROWSER L'authentification a lieu dans un navigateur.
acceptHeader chaine | Longueur : 1-2048 | requis

Contenu exact du header HTTP "accept" tel qu'envoyé par le navigateur du client.
userAgent chaine | Longueur : 1-2048 | requis

Contenu exact de l'entête HTTP "user-agent" envoyé par le navigateur. Doit être tronqué si la valeur dépasse 2048 caractères.
ip chaine | Longueur : 1-45 | optionnel

Adresse IP du navigateur telle que renvoyée dans les entêtes HTTP par le client. Format IPV4 (ex: 1.12.123.255) ou IPV6 (ex: 2011:0db8:85a3:0101:0101:8a2e:0370:7334).
javaEnabled booléen | Longueur : 1 | requis

Booléen qui représente la capacité du navigateur à exécuter du Java. La valeur est celle retournée par la fonction "navigator.javaEnabled()" et peut être true ou false.
language chaine | Longueur : 2-5 | requis

Langue du navigateur. Obtenue du navigateur client via la propriété "navigator.language".
colorDepth entier | Longueur : 1-12 | requis

Valeur représentant la profondeur de la palette de couleurs utilisée pour afficher les images, en bits par pixel. Obtenue du navigateur client via la propriété "screen.colorDepth".
screenHeight entier | Longueur : 1-6 | requis

La hauteur totale de l'écran du client en pixels. La valeur est celle retournée par la propriété "screen.height".
screenWidth entier | Longueur : 1-6 | requis

La largeur totale de l'écran du client en pixels. La valeur est celle retournée par la propriété "screen.width".
timeZoneOffset chaine | Longueur : 3-4 | requis

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.
paymentForm objet JSON | requis

Objet contenant les données de la carte.
Détails de l'objet
NOM DESCRIPTION
networkPreference énumération | requis

Nom du réseau préférentiel préconisé par le marchand.
Valeurs possibles
Valeur Description
AMEX Réseau American Express (Safekey)
CB Réseau Carte Bancaire
DINERS Réseau Diners
DISCOVER Réseau Discover
MASTERCARD Réseau Mastercard
OSB Réseau OSB
VISA Réseau Visa
accountType énumération | optionnel

Type de carte.
Valeurs possibles
Valeur Description
CREDIT Carte de crédit
DEBIT Carte de débit
pan chaine | Longueur : 16-19 | requis

Primary Account Number. Numéro de carte.
expiryMonth entier | Longueur : 2 | requis

Mois d'expiration sur 2 chiffres (par exemple : "09" pour septembre).
expiryYear entier | Longueur : 2 | requis

Année d'expiration sur 2 chiffres (par exemple : "28" pour 2028).
cardHolderName chaine | Longueur : 0-45 | recommandé

Nom et prénom du porteur de la carte.
installmentNumber entier | Longueur : 3 | optionnel

Nombre d'échéances.
protocolRequest objet JSON | requis

Objet contenant les informations sur le protocole d'authentification.
Détails de l'objet
NOM DESCRIPTION
name énumération | requis

Nom du protocole d'authentification du porteur de carte.
Valeurs possibles
Valeur Description
THREEDS Protocole 3D Secure
OSB Protocole OTP OSB
version chaine | Longueur : 1 | optionnel

Version du protocole d'authentification à utiliser.
Valeurs possibles
Valeur Description
1 Protocole OTP OSB
2 Protocole 3D Secure 2
challengePreference énumération | recommandé

Permet de demander une authentication avec ou sans intéraction de l'acheteur.
Valeurs possibles
Valeur Description
NO_PREFERENCE Le choix de la préférence est délégué à l'émetteur de la carte.
NO_CHALLENGE_REQUESTED Permet de demander une authentification sans interaction (frictionless).
CHALLENGE_REQUESTED Permet de demander une authentification forte pour la transaction.
CHALLENGE_MANDATED Permet d'indiquer que pour des raisons réglementaires, une authentification forte est requise pour la transaction.
DATA_ONLY Permet de demander une authentification sans interaction, prise en charge par le DS au lieu de l'ACS de la banque émettrice. **La transaction ne bénéficiera pas du transfert de responsabilité**. L'authentification sera désactivée si le réseau n'est pas compatible avec cette fonctionnalité. Le service PCI/Charge/Authenticate retourne un code erreur INT_808, si le champ transactionCategory n'est pas valorisé à PAYMENT.
DATA_SHARE_ONLY Permet de demander une transaction sans interaction du porteur mais pour laquelle le marchand souhaite partager les données via le processus 3DS avec l'émetteur pour réduire le risque de refus lors de l'autorisation.
merchant objet JSON | requis

Objet contenant les informations sur le contrat.
Détails de l'objet
NOM DESCRIPTION
mid chaine | Longueur : 1-128 | requis

Merchant ID. Numéro de contrat commerçant.
tid chaine | Longueur : 0-128 | optionnel

Terminal ID. Identifiant du point de vente défini sur le contrat d'acceptation.
Ce champ est utilisé uniquement en Colombie afin de choisir entre REDEBAN et CREDIBANCO.
name chaine | Longueur : 0-25 | optionnel

Nom du marchand.
mcc chaine | Longueur : 10 | optionnel

Merchant Category Code. Code spécifique au DS émetteur décrivant le type d'activité, de produit ou de service du marchand.
recurring objet JSON | optionnel

Objet contenant les informations sur l'abonnement.
Détails de l'objet
NOM DESCRIPTION
expiryDate chaine | Longueur : 10 | optionnel

Date d'expiration de l'abonnement (par exemple: 2025-12-31).
frequency objet JSON | Longueur : 0-150 | optionnel

Objet contenant les informations sur la fréquence de l'abonnement.
Détails de l'objet
NOM DESCRIPTION
value entier | Longueur : 3 | optionnel

Nombre minimal d'unités entre deux paiements (par exemple : 12). Voir champ unit .
unit énumération | optionnel

Unité de fréquence de l'abonnement.
Valeurs possibles
Valeur Description
DAY En jours.
MONTH En mois.
YEAR En années.

Retrouvez la description des champs dans notre playground : PCI/Charge/Authenticate.

Il est recommandé de transmettre un maximum d'informations 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.secure.osb.pf/api-payment/V4/PCI/Charge/Authenticate
{
  "amount": 1230,
  "currency": "XPF",
  "transactionCategory": "PAYMENT",
  "productType": "GOODS_OR_SERVICE_PURCHASE",
  "merchant": {
    "mid": "1234567"
  },
  "paymentForm":{
    "cardHolderName": "John Doe",
    "pan": "4970110000000013",
    "expiryMonth": "02",
    "expiryYear": "24",
    "networkPreference": "VISA"
  },
  "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"
  },  
  "protocolRequest": {
    "name": "THREEDS",
    "version": "2",
    "challengePreference": "NO_PREFERENCE"
  }
}
/**
 * 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"];

?>

Exemple de réponse

La suite du processus dépend de l'objet contenu dans la réponse : AuthenticationResponseData :

  1. Objet AuthenticationResult :
  • Procédez directement à la demande d'autorisation (pas d'authentification du porteur)
  • Exemple, avec une demande de FRICTIONLESS :
{
 "webService":"PCI/Charge/Authenticate",
 "version":"V4",
 "applicationVersion":"5.23.0",
 "serverDate":"2021-05-05T09:33:32+00:00",
 "ticket":"3b68064f80f346919828dee761bd22b5",
 "applicationProvider":"",
 "metadata":null,
 "status":"SUCCESS",
 "mode":"TEST",
 "serverUrl":"https://api.secure.osb.pf",
 "_type":"V4/WebService/Response",
 "answer":{
  "id":"1fec4a93-3208-4602-be55-803261bdbccc",
  "protocol":{
   "name":"THREEDS",
   "version":"2.1.0",
   "network":"VISA",
   "challengePreference":"NO_PREFERENCE",
   "simulation":true,
   "_type":"V4/Charge/Authenticate/Protocol"
  }
  ,"value":{
   "authenticationType":"FRICTIONLESS",
   "authenticationId":{
    "authenticationIdType":"dsTransId",
    "value":"cd85dd04-4bd8-47e4-b42a-708ded17b3cf",
    "_type":"V4/Charge/Authenticate/AuthenticationId"
   },
   "authenticationValue":{
    "authenticationValueType":"CAVV",
    "value":"udjlTuaT4fHRNwKRifj1t+Zn/6k=",
    "_type":"V4/Charge/Authenticate/AuthenticationValue"
   },
   "status":"SUCCESS",
   "commerceIndicator":"05",
   "extension":{
    "authenticationType":"THREEDS_V2",
    "threeDSServerTransID":"1fec4a93-3208-4602-be55-803261bdbccc",
    "dsTransID":"cd85dd04-4bd8-47e4-b42a-708ded17b3cf",
    "acsTransID":"a11081a6-268f-42bc-8356-0aacf74d2565",
    "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
   },
   "reason":{
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason"
   },
   "_type":"V4/Charge/Authenticate/AuthenticationResult"
  },
  "_type":"V4/AuthenticationResponseData"
 }
}
  1. Objet AuthenticationInstruction :
  • Procédez à l'authentification du porteur (voir étape 2: Traitement des instructions).
  • Exemple, avec une instruction FINGERPRINT (3DS Method).
{
 "webService":"PCI/Charge/Authenticate",
 "version":"V4",
 "applicationVersion":"5.22.0",
 "serverDate":"2021-05-03T15:02:56+00:00",
 "ticket":"c295ad67f65341529c1db6760df400fd",
 "applicationProvider":"",
 "metadata":null,
 "status":"SUCCESS",
 "mode":"TEST",
 "serverUrl":"https://api.secure.osb.pf",
 "_type":"V4/WebService/Response",
 "answer":{
  "id":"b5bdf588-df35-4d56-8852-a68bd9c20147",
  "protocol":{
   "name":"THREEDS","
   version":"2.1.0",
   "network":"VISA",
   "challengePreference":"NO_PREFERENCE",
   "simulation":true,
   "_type":"V4/Charge/Authenticate/Protocol"
  },
  "value":{
   "instructionType":"FORM",
   "name":"FINGERPRINT",
   "timeout":10,
   "target":{
    "element":"IFRAME",
    "visible":false,
    "_type":"V4/Charge/Authenticate/InstructionTarget"
   },
   "http":{
    "method":"POST",
    "url":"<https://acs.sg.com/acs/v2/3dsMethod>",
    "body":{
     "threeDSMethodData":"eyJ0aHJlZURzTW..."
    },
    "_type":"V4/Charge/Authenticate/HttpRequest"
   },
   "_type":"V4/Charge/Authenticate/AuthenticationInstruction"
  },
  "_type":"V4/AuthenticationResponseData"
 }
}

2. Traitement des instructions

La réponse à l'appel au service PCI/Charge/Authenticate 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 préconisé de sauvegarder les paramètres d'entrée de l'appel initial au service PCI/Charge/Authenticate ainsi que le champ id contenu dans la réponse. Ces paramètres sont requis pour la suite de l'authentification.

Exemple d'appel de la fonction createInstructionIframe en PHP

//Call the charge/Authenticate method
$obj = authenticate($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['RequestParams']= $param_request;
		$_SESSION['requestId'] = $response['id'];
		
		//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/Authenticate afin de décoder son contenu.

Utilisez les champs suivants dans votre requête :

NOM DESCRIPTION
amount entier | Longueur : 1-12 | requis

Montant de la transaction exprimé dans la plus petite fraction de la devise (par exemple : 30050 pour 30050 XPF).
currency chaine | Longueur : 3 | requis

Code de la devise selon la norme ISO 4217 alpha-3 (par exemple : "XPF" pour le franc CFP).
Valeurs possibles
Devise CODIFICATION ISO 4217 Unité fractionnaire
Dollar australien (036)AUD 2
Renminbi yuan chinois (156)CNY 1
Franc Djibouti (262)DJF 0
Euro (978)EUR 2
Dollar de Fidji (242)FJD 2
Livre Sterling (826)GBP 2
Dollar de Hong Kong (344)HKD 2
Yen (392)JPY 0
Riel Cambodgien (116)KHR 0
Kip laotien (418)LAK 0
Dollar néo-zélandais (554)NZD 2
Dollar des Îles Salomon (090)SBD 2
Baht thailandais (764)THB 2
Dollar des États-Unis (840)USD 2
Vatu des Îles Vanuatu (548)VUV 0
Franc CFP (953)XPF 0
productType énumération | optionnel

Type de produit concerné par la transaction.
Valeurs possibles
Valeur Description
ACCOUNT_FUNDING Versement sur un compte
CHECK_ACCEPTANCE Vérification d'acceptation
GOODS_OR_SERVICE_PURCHASE Achat de bien ou de service. Valeur utilisée par défaut.
PREPAID_ACTIVATION_AND_LOAD Activation et charge d'une carte prépayée
QUASI_CASH_TRANSACTION Transactions en quasi-espèces (ex : chèque vacances, billet de loterie, etc.)
transactionCategory énumération | requis

Catégorie de la transaction. Doit être valorisé à PAYMENT.
customer objet JSON | recommandé

Objet contenant les données de l'acheteur.
Détails de l'objet
NOM DESCRIPTION
reference chaine | Longueur : 0-80 | optionnel

Identifiant de l'acheteur chez le marchand.
email chaine | Longueur : 0-150 | recommandé

Adresse e-mail
accountDetails objet JSON | recommandé

Objet détaillant les informations du compte de l'acheteur sur le site marchand.
Détails de l'objet
NOM DESCRIPTION
authenticationMethod énumération | recommandé

Méthode d'authentification de l'acheteur sur le site marchand.
Valeurs possibles
Valeur Description
GUEST Pas d'authentification (invité).
PERSONAL_CREDENTIALS Utilisation d'un compte créé sur le site marchand.
FEDERATED_CREDENTIALS Utilisation de l'authentification fédérée.
ISSUER_CREDENTIALS Utilisation d'identifiants fournis par l'émetteur.
EXTERNAL_CREDENTIALS Authentification par un tiers.
FIDO_CREDENTIALS Utilisation de l'authentification FIDO (Fast IDentity Online).
billingDetails objet JSON | optionnel

Objet détaillant les informations de l'acheteur.
Détails de l'objet
NOM DESCRIPTION
title chaine | Longueur : 0-63 | optionnel

Civilité de l'acheteur.
Exemples de valeurs
  • Mr
  • M.
  • Mme
category énumération | optionnel

Type de client.
Valeurs possibles
Valeur Description
PRIVATE Client de type Particulier.
COMPANY Client de type Société.
firstName chaine | Longueur : 0-63 | optionnel

Prénom.
lastName chaine | Longueur : 0-63 | optionnel

Nom.
phonenumber chaine | Longueur : 0-32 | optionnel

Numéro de téléphone fixe.
Exemples de valeurs
  • 0123456789
  • +33123456789
  • 0033123456789
  • (00.571) 638.14.00
  • 40 41 42 42
streetNumber chaine | Longueur : 0-64 | optionnel

Numéro de rue.
address chaine | Longueur : 0-255 | optionnel

Adresse de facturation.
address2 chaine | Longueur : 0-255 | optionnel

Informations complémentaires sur l'adresse.
district chaine | Longueur : 0-127 | optionnel

Quartier.
zipCode chaine | Longueur : 0-64 | optionnel

Code postal.
city chaine | Longueur : 0-128 | optionnel

Ville.
state chaine | Longueur : 0-127 | optionnel

Région.
country chaine | Longueur : 2 | optionnel

Code pays (norme ISO 3166-1 alpha-2).
Exemples de valeurs
Valeur Description
AT AUTRICHE
BE BELGIQUE
FR CORSE
CI COTE D'IVOIRE
FR FRANCE
GP GUADELOUPE
MQ MARTINIQUE
NC NOUVELLE-CALÉDONIE
PM ST-PIERRE-ET-MIQUELON
PF POLYNESIE FRANCAISE
language chaine | Longueur : 2 | optionnel

Code langue (norme ISO 639-1).
Exemples de valeurs
Valeur Description
DE Allemand (Allemagne)
EN Anglais (Royaume Uni)
EN Anglais (Etats-Unis )
ZH Chinois (Traditionnel)
ES Espagnol (Espagne)
ES Espagnol (Chili)
FR Français (France)
IT Italien (Italie)
JP Japonais (Japon)
NL Néerlandais (Pays-Bas)
PL Polonais (Pologne)
PT Portugais (Brésil)
PT Portugais (Portugal)
RU Russe (Russie)
cellPhonenumber chaine | Longueur : 0-32 | optionnel

Numéro de téléphone mobile.
Exemples de valeurs
  • 0623456789
  • +33623456789
  • 0033623456789
  • (+34) 824 65 43 21
  • 87 77 12 34
identityCode chaine | Longueur : 0-150 | optionnel

Identifiant national.
identityType chaine | Longueur : 0-3 | optionnel

Type de pièce d'identité.
Valeurs possibles
Pays Type Description
Argentina DNI Documento Nacional de Identidad.
Brasil CNPJ Cadastro Nacional da Pessoa Jurídica.
CPF Cadastro de Pessoas Físicas.
Colombia CC Cédula de ciudadania.
TI Tarjeta de Identidad.
CE Cédula de Extranjeria.
NI Número de Identificación Tributaria.
PS Pasaporte.
Peru DNI_PER Documento National de Identidad.
PAR Partida de Nacimiento.
PAS Pasaporte.
LMI Libreta Militar.
NAN Otro.
legalName chaine | Longueur : 0-100 | optionnel

Raison Sociale.
shippingDetails objet JSON | optionnel

Objet détaillant les informations de livraison.
Détails de l'objet
NOM DESCRIPTION
category énumération | optionnel

Type de client.
Valeurs possibles
Valeur Description
PRIVATE Client de type Particulier.
COMPANY Client de type Société.
firstName chaine | Longueur : 0-63 | optionnel

Prénom.
lastName chaine | Longueur : 0-63 | optionnel

Nom.
phonenumber chaine | Longueur : 0-32 | optionnel

Numéro de téléphone fixe.
Exemples de valeurs
  • 0123456789
  • +33123456789
  • 0033123456789
  • (00.571) 638.14.00
  • 40 41 42 42
streetNumber chaine | Longueur : 0-64 | optionnel

Numéro de rue.
address chaine | Longueur : 0-255 | optionnel

Adresse de livraison.
address2 chaine | Longueur : 0-255 | optionnel

Informations complémentaires sur l'adresse de livraison.
district chaine | Longueur : 0-127 | optionnel

Quartier.
zipCode chaine | Longueur : 0-64 | optionnel

Code postal.
city chaine | Longueur : 0-128 | optionnel

Ville.
state chaine | Longueur : 0-127 | optionnel

Région.
country chaine | Longueur : 2 | optionnel

Code pays (norme ISO 3166-1 alpha-2).
Exemples de valeurs
Valeur Description
AT AUTRICHE
BE BELGIQUE
FR CORSE
CI COTE D'IVOIRE
FR FRANCE
GP GUADELOUPE
MQ MARTINIQUE
NC NOUVELLE-CALÉDONIE
PM ST-PIERRE-ET-MIQUELON
PF POLYNESIE FRANCAISE
deliveryCompanyName chaine | Longueur : 0-127 | optionnel

Nom de la société de livraison.
shippingSpeed énumération | optionnel

Délai de livraison.
Valeurs possibles
Valeur Description
STANDARD Livraison standard.
EXPRESS Livraison en moins de 24h.
PRIORITY Livraison Prioritaire (Click & Collect).
shippingMethod énumération | optionnel

Mode de livraison.
Valeurs possibles
Valeur Description
RECLAIM_IN_SHOP Retrait de marchandise en magasin.
RELAY_POINT Utilisation d'un réseau de points de retrait tiers (Kiala, Alveol, etc).
RECLAIM_IN_STATION Retrait dans un aéroport, une gare ou une agence de voyage.
PACKAGE_DELIVERY_COMPANY Livraison par transporteur (Colissimo, UPS, etc).
ETICKET Emission d'un billet électronique, téléchargement de produit virtuel.

Valeurs réservées à un usage futur :
Valeur Description
CARD_HOLDER_ADDRESS Livraison chez l'acheteur.
VERIFIED_ADDRESS Livraison à une adresse vérifiée.
NOT_VERIFIED_ADDRESS Livraison à une adresse non vérifiée.
SHIP_TO_STORE Livraison en magasin.
DIGITAL_GOOD Livraison digitale.
ETRAVEL_OR_ETICKET Billet électronique.
OTHER Autre.
PICKUP_POINT Retrait en point relais.
AUTOMATED_PICKUP_POINT Retrait en point relais automatique.
identityCode chaine | Longueur : 0-150 | optionnel

Identifiant national.
legalName chaine | Longueur : 0-100 | optionnel

Raison Sociale.
shoppingCart objet JSON | optionnel

Objet détaillant le contenu du panier.
Détails de l'objet
NOM DESCRIPTION
insuranceAmount entier | Longueur : 1-12 | optionnel

Montant de l'assurance pour l'ensemble de la commande, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
shippingAmount entier | Longueur : 1-12 | optionnel

Montant des frais de livraison pour l'ensemble de la commande, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
taxAmount entier | Longueur : 1-12 | optionnel

Montant des taxes pour l'ensemble de la commande, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
cartItemInfo tableau | optionnel

Liste d'objets Customer/ShoppingCartItem décrivant chaque article du panier.
Détails de l'objet
NOM DESCRIPTION
productLabel chaine | Longueur : 0-255 | optionnel

Nom du produit.
productType énumération | optionnel

Type de produit.
Valeurs possibles
Valeur Description
FOOD_AND_GROCERY Produits alimentaires et d'épicerie.
AUTOMOTIVE Automobile / Moto.
ENTERTAINMENT Divertissement / Culture.
HOME_AND_GARDEN Maison et jardin.
HOME_APPLIANCE Équipement de la maison.
AUCTION_AND_GROUP_BUYING Ventes aux enchères et achats groupés.
FLOWERS_AND_GIFTS Fleurs et cadeaux.
COMPUTER_AND_SOFTWARE Ordinateurs et logiciels.
HEALTH_AND_BEAUTY Santé et beauté.
SERVICE_FOR_INDIVIDUAL Services à la personne.
SERVICE_FOR_BUSINESS Services aux entreprises.
SPORTS Sports.
CLOTHING_AND_ACCESSORIES Vêtements et accessoires.
TRAVEL Voyage.
HOME_AUDIO_PHOTO_VIDEO Son, image et vidéo.
TELEPHONY Téléphonie.
productRef chaine | Longueur : 0-64 | optionnel

Référence du produit.
productQty entier | Longueur : 1-12 | optionnel

Quantité du produit.
productAmount entier | Longueur : 1-12 | optionnel

Montant du produit, exprimé dans la plus petite unité de la devise (par exemple : 30050 pour 30050 XPF).
productVat chaine | Longueur : 1-12 | optionnel

Montant de la taxe sur le produit.
Type de valeurs possibles
  • Un nombre entier

    Pour exprimer un montant en centime appliqué sur le produit concerné.

  • Un nombre décimal

    Pour exprimer un pourcentage appliqué sur le montant du produit concerné avec maximum 4 chiffres après la virgule.

    La décimale est obligatoire pour exprimer un pourcentage. La décimale est marquée par le caractère ".".

previousAuthentication objet JSON | ignoré

Objet contenant les données de l'authentification précédente.
device objet JSON | requis

Objet décrivant les informations sur le navigateur.
Détails de l'objet
NOM DESCRIPTION
deviceType énumération | requis

Type d'appareil sur lequel s'effectue l'authentification.
acceptHeader chaine | Longueur : 1-2048 | requis

Contenu exact du header HTTP "accept" tel qu'envoyé par le navigateur du client.
userAgent chaine | Longueur : 1-2048 | requis

Contenu exact de l'entête HTTP "user-agent" envoyé par le navigateur. Doit être tronqué si la valeur dépasse 2048 caractères.
ip chaine | Longueur : 1-45 | optionnel

Adresse IP du navigateur telle que renvoyée dans les entêtes HTTP par le client. Format IPV4 (ex: 1.12.123.255) ou IPV6 (ex: 2011:0db8:85a3:0101:0101:8a2e:0370:7334).
javaEnabled booléen | Longueur : 1 | requis

Booléen qui représente la capacité du navigateur à exécuter du Java. La valeur est celle retournée par la fonction "navigator.javaEnabled()" et peut être true ou false.
language chaine | Longueur : 2-5 | requis

Langue du navigateur. Obtenue du navigateur client via la propriété "navigator.language".
colorDepth entier | Longueur : 1-12 | requis

Valeur représentant la profondeur de la palette de couleurs utilisée pour afficher les images, en bits par pixel. Obtenue du navigateur client via la propriété "screen.colorDepth".
screenHeight entier | Longueur : 1-6 | requis

La hauteur totale de l'écran du client en pixels. La valeur est celle retournée par la propriété "screen.height".
screenWidth entier | Longueur : 1-6 | requis

La largeur totale de l'écran du client en pixels. La valeur est celle retournée par la propriété "screen.width".
timeZoneOffset chaine | Longueur : 3-4 | requis

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.
paymentForm objet JSON | requis

Objet contenant les données de la carte.
Détails de l'objet
NOM DESCRIPTION
networkPreference énumération | requis

Nom du réseau préférentiel préconisé par le marchand.
Valeurs possibles
Valeur Description
AMEX Réseau American Express (Safekey)
CB Réseau Carte Bancaire
DINERS Réseau Diners
DISCOVER Réseau Discover
MASTERCARD Réseau Mastercard
OSB Réseau OSB
VISA Réseau Visa
accountType énumération | optionnel

Type de carte.
Valeurs possibles
Valeur Description
CREDIT Carte de crédit
DEBIT Carte de débit
pan chaine | Longueur : 16-19 | requis

Primary Account Number. Numéro de carte.
expiryMonth entier | Longueur : 2 | requis

Mois d'expiration sur 2 chiffres (par exemple : "09" pour septembre).
expiryYear entier | Longueur : 2 | requis

Année d'expiration sur 2 chiffres (par exemple : "28" pour 2028).
cardHolderName chaine | Longueur : 0-45 | recommandé

Nom et prénom du porteur de la carte.
installmentNumber entier | Longueur : 3 | optionnel

Nombre d'échéances.
protocolRequest objet JSON | requis

Objet décrivant le mode d'authentification souhaité.
Détails de l'objet
NOM DESCRIPTION
name énumération | requis

Nom du protocole d'authentification du porteur de carte.
Valeurs possibles
Valeur Description
THREEDS Protocole 3D Secure
OSB Protocole OTP OSB
version chaine | Longueur : 1 | optionnel

Version du protocole d'authentification à utiliser.
Valeurs possibles
Valeur Description
1 Protocole OTP OSB
2 Protocole 3D Secure 2
challengePreference énumération | recommandé

Permet de demander une authentication avec ou sans intéraction de l'acheteur.
Valeurs possibles
Valeur Description
NO_PREFERENCE Le choix de la préférence est délégué à l'émetteur de la carte.
NO_CHALLENGE_REQUESTED Permet de demander une authentification sans interaction (frictionless).
CHALLENGE_REQUESTED Permet de demander une authentification forte pour la transaction.
CHALLENGE_MANDATED Permet d'indiquer que pour des raisons réglementaires, une authentification forte est requise pour la transaction.
DATA_ONLY Permet de demander une authentification sans interaction, prise en charge par le DS au lieu de l'ACS de la banque émettrice. **La transaction ne bénéficiera pas du transfert de responsabilité**. L'authentification sera désactivée si le réseau n'est pas compatible avec cette fonctionnalité. Le service PCI/Charge/Authenticate retourne un code erreur INT_808, si le champ transactionCategory n'est pas valorisé à PAYMENT.
DATA_SHARE_ONLY Permet de demander une transaction sans interaction du porteur mais pour laquelle le marchand souhaite partager les données via le processus 3DS avec l'émetteur pour réduire le risque de refus lors de l'autorisation.
merchant objet JSON | requis

Objet contenant les informations sur le contrat.
Détails de l'objet
NOM DESCRIPTION
mid chaine | Longueur : 1-128 | requis

Merchant ID. Numéro de contrat commerçant.
tid chaine | Longueur : 0-128 | optionnel

Terminal ID. Identifiant du point de vente défini sur le contrat d'acceptation.
Ce champ est utilisé uniquement en Colombie afin de choisir entre REDEBAN et CREDIBANCO.
name chaine | Longueur : 0-25 | optionnel

Nom du marchand.
mcc chaine | Longueur : 10 | optionnel

Merchant Category Code. Code spécifique au DS émetteur décrivant le type d'activité, de produit ou de service du marchand.
recurring objet JSON | optionnel

Objet contenant les informations sur l'abonnement.
Détails de l'objet
NOM DESCRIPTION
expiryDate chaine | Longueur : 10 | optionnel

Date d'expiration de l'abonnement (par exemple: 2025-12-31).
frequency objet JSON | Longueur : 0-150 | optionnel

Objet contenant les informations sur la fréquence de l'abonnement.
Détails de l'objet
NOM DESCRIPTION
value entier | Longueur : 3 | optionnel

Nombre minimal d'unités entre deux paiements (par exemple : 12). Voir champ unit.
unit énumération | optionnel

Unité de fréquence de l'abonnement.
Valeurs possibles
Valeur Description
DAY En jours.
MONTH En mois.
YEAR En années.
id chaine | Longueur : 36 | requis

Identifiant de la requête d'authentification fourni dans la réponse à l'appel initial.
instructionResult objet JSON | requis

Objet contenant le détail de l'instruction reçu dans l'événement JavaScript LYRA_AUTH_INSTRUCTION_RESULT.

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.secure.osb.pf/api-payment/V4/PCI/Charge/Authenticate
{
  "amount": 1230,
  "currency": "XPF",
  "transactionCategory": "PAYMENT",
  "productType": "GOODS_OR_SERVICE_PURCHASE",
  "merchant": {
    "mid": "1234567"
  },
  "paymentForm":{
    "pan": "4970110000000013",
    "expiryMonth": "02",
    "expiryYear": "24",
	  "networkPreference": "VISA"
  },
  "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"
  },  
  "protocolRequest": {
    "name": "THREEDS",
    "version": "2",
    "challengePreference": "NO_PREFERENCE"
  },  
  "id": "c82794e9-9c20-44a8-9297-b70e1e7c4006",  
  "instructionResult": {
    "name" : "CHALLENGE",    
    "protocol" : {
      "name" : "THREEDS",
      "version" : "1.0.2",
      "network" : "VISA",
      "challengePreference": "NO_PREFERENCE",
      "simulation": false
    },
    "value": "eyJhbGciOiJIUz..."
  }
}
/**
 * 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. Analyse du résultat de l'authentification

Le processus d'authentification est terminé. La réponse contient les données nécessaires pour procéder à la demande d'autorisation.

Ci-dessous quelques exemples de données retournées après l'authentification du porteur :

Authentification Frictionless 3DS2

(avec ou sans 3DS Method)

```json "answer":{ "id":"3b25e3ed-5d48-4f99-af61-0d5db9e3b18e", "protocol":{ "name":"THREEDS", "version":"2.1.0", "network":"VISA", "challengePreference":"NO_PREFERENCE", "simulation":true, "_type":"V4/Charge/Authenticate/Protocol" }, "value":{ "authenticationType":"FRICTIONLESS", "authenticationId":{ "authenticationIdType":"dsTransId", "value":"18e46ff7-b882-4102-9af4-aef9f40ee6a6", "_type":"V4/Charge/Authenticate/AuthenticationId" }, "authenticationValue":{ "authenticationValueType":"CAVV", "value":"PdY1V9f/aHxC2wbZt4/7Z6Q9f44=", "_type":"V4/Charge/Authenticate/AuthenticationValue" }, "status":"SUCCESS", "commerceIndicator":"05", "extension":{ "authenticationType":"THREEDS_V2", "threeDSServerTransID":"3b25e3ed-5d48-4f99-af61-0d5db9e3b18e", "dsTransID":"18e46ff7-b882-4102-9af4-aef9f40ee6a6", "acsTransID":"410d9fb4-8db1-483e-9a80-f94c3a79017e", "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2" }, "reason":{ "_type":"V4/Charge/Authenticate/AuthenticationResultReason" }, "_type":"V4/Charge/Authenticate/AuthenticationResult" }, "_type":"V4/AuthenticationResponseData" } ```

Authentification challenge 3DS2 réussie

"answer":{
"id":"3b25e3ed-5d48-4f99-af61-0d5db9e3b18e",
"protocol":{
  "name":"THREEDS",
  "version":"2.1.0",
  "network":"VISA",
  "challengePreference":"NO_PREFERENCE",
  "simulation":true,
  "_type":"V4/Charge/Authenticate/Protocol"
},
"value":{
  "authenticationType":"CHALLENGE",
  "authenticationId":{
    "authenticationIdType":"dsTransId",
    "value":"18e46ff7-b882-4102-9af4-aef9f40ee6a6",
    "_type":"V4/Charge/Authenticate/AuthenticationId"
  },
  "authenticationValue":{
    "authenticationValueType":"CAVV",
    "value":"PdY1V9f/aHxC2wbZt4/7Z6Q9f44=",
    "_type":"V4/Charge/Authenticate/AuthenticationValue"
  },
  "status":"SUCCESS",
  "commerceIndicator":"05",
  "extension":{
    "authenticationType":"THREEDS_V2",
    "threeDSServerTransID":"3b25e3ed-5d48-4f99-af61-0d5db9e3b18e",
    "dsTransID":"18e46ff7-b882-4102-9af4-aef9f40ee6a6",
    "acsTransID":"410d9fb4-8db1-483e-9a80-f94c3a79017e",
    "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
  },
  "reason":{
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason"
  },
  "_type":"V4/Charge/Authenticate/AuthenticationResult"
},
"_type":"V4/AuthenticationResponseData"
}

Authentification challenge 3DS2 en échec

"answer":{
"id":"4ceb0194-8900-41c6-8ef4-debdbe7421b1",
"protocol":{
  "name":"THREEDS",
  "version":"2.1.0",
  "network":"VISA",
  "challengePreference":"NO_PREFERENCE",
  "simulation":true,
  "_type":"V4/Charge/Authenticate/Protocol"
},
"value":{
  "authenticationType":"CHALLENGE",
  "authenticationId":{
    "authenticationIdType":"dsTransId",
    "value":"e8286d62-006e-413e-ad3b-328503b14e71",
    "_type":"V4/Charge/Authenticate/AuthenticationId"
  },
  "status":"FAILED",
  "extension":{
    "authenticationType":"THREEDS_V2",
    "threeDSServerTransID":"fdce5a18-2f2f-46c7-bdd4-3bd40b7e816d",
    "dsTransID":"e8286d62-006e-413e-ad3b-328503b14e71",
    "acsTransID":"54feb2ac-9666-4ce3-86e5-d8f947cebd87",
    "transStatusReason":"01",
    "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
  },
  "reason":{
    "code":"CARD_AUTHENTICATION_FAILED",
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason"
  },
  "_type":"V4/Charge/Authenticate/AuthenticationResult"
},
"_type":"V4/AuthenticationResponseData"
}

Authentification challenge 3DS2 en timeout

"answer":{
"id":"a30802af-24e3-4071-8e07-331bfbc40cfa",
"protocol":{
  "name":"THREEDS",
  "version":"1.0.2",
  "network":"VISA",
  "challengePreference":"NO_PREFERENCE",
  "simulation":true,
  "_type":"V4/Charge/Authenticate/Protocol"
},
"value":{
  "authenticationType":"CHALLENGE",			
  "status":"FAILED",
  "extension":{
    "code":"AUTHENTICATION_ERROR",
    "message":"Challenge timeout",
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason",
  },		
  "reason":{
    "code":"AUTHENTICATION_ERROR",
    "message":"Challenge timeout",
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason"
  },
  "_type":"V4/Charge/Authenticate/AuthenticationResult"
},
"_type":"V4/AuthenticationResponseData"
}

Erreur technique

"answer":{
"id":"f8fd5bc0-5297-4a1c-84f3-7b3cf1b3ccaf",
"protocol":{
  "name":"THREEDS",
  "version":"1.0.2",
  "network":"VISA",
  "challengePreference":"NO_PREFERENCE",
  "simulation":true,
  "_type":"V4/Charge/Authenticate/Protocol"
},
"value":{
  "status":"FAILED",
  "extension":{
    "authenticationType":"THREEDS_V1",
    "enrolled":"Y",
    "signatureValid":false,
    "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV1"
  },
  "reason":{
    "code":"INVALID_PARES_SIGNATURE",
    "message":"#308 The signature of received PARes message is not valid - ACS concerned : null",
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason"
  },
  "_type":"V4/Charge/Authenticate/AuthenticationResult"
},
"_type":"V4/AuthenticationResponseData"
}

Authentification OTP OSB réussie

"answer":{
"id":"46ba3e89-48bf-4f70-975c-ddcba2727fbf",
"protocol":{
  "name":"OSB",
  "version":"1.0.0",
  "network":"OSB",
  "challengePreference":"NO_PREFERENCE",
  "simulation":true,
  "_type":"V4/Charge/Authenticate/Protocol"
},
"value":{
  "authenticationType":"CHALLENGE",
  "authenticationId":{
    "authenticationIdType":"dsTransId",
    "value":"46ba3e89-48bf-4f70-975c-ddcba2727fbf",
    "_type":"V4/Charge/Authenticate/AuthenticationId"
  },
  "authenticationValue":{
    "authenticationValueType":"CAVV",
    "value":"SmdiTlZ5eXVSdmpNQVlXNGdxeW4=",
    "_type":"V4/Charge/Authenticate/AuthenticationValue"
  },
  "status":"SUCCESS",
  "extension":{
    "authenticationType":"OSB_V1",
    "responseCode":"00",
    "infoSupp":[
      "simulator",
      "input error count : 0"
    ],
    "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionOsbV1"
  },
  "_type":"V4/Charge/Authenticate/AuthenticationResult"
},
"_type":"V4/AuthenticationResponseData"
}
© 2025 Tous droits réservés à PayZen by OSB
25.18-1.11