Afin de faciliter l'intégration de la solution, notre librairie JavaScript collecte les données de l'équipement et du navigateur du client, communique directement avec le 3DS Server et gère l'interaction du porteur de carte pendant le challenge.
Dans le HEAD
de la page, ajoutez la librairie JavaScript dans une balise script
.
<head>
...
<script src="https://epaync.nc/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
...
</head>
Si pour des raisons de sécurité (contraintes PCI-DSS) vous devez implémenter le SRI, consultez la page : Intégrer l'intégrité des sous-ressources (SRI).
2. Initier une demande d'authentification du porteur
Appelez le service PCI/Authentication/CreateSession 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). |
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 | 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 | 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). | language | chaine | Longueur : 2 | optionnel
Code langue (norme ISO 639-1). | 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é. | 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). |
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 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 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 | 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 |
| version | chaine | Longueur : 1 | optionnel
Version du protocole d'authentification à utiliser. | 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. |
|
|
|
ianTargetUrl | chaine | Longueur : 1-255 | requis
URL de notification appelée à la fin de l'authentification. |
D'autres champs facultatifs sont disponibles. Retrouvez la description des champs dans notre playground.
/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://epaync.nc/api-payment/V4/PCI/Authentication/CreateSession
{
"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"
},
"protocolRequest": {
"name": "THREEDS",
"version": "2",
"challengePreference": "NO_PREFERENCE"
},
"ianTargetUrl": "https://myiantargeturl.com"
}
/**
* 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"];
?>
Lors de la réponse AuthenticationSessionResponse
, vous trouverez les champs suivants :
answer.operationSessionId
: l'identifiant de la session d’authentification (à conserver) answer.operationUrl
: URL à transmettre à la librairie JavaScript
Retrouvez la description des champs dans notre playground.
{
"webService":"PCI/Authentication/CreateSession",
"version":"V4",
"applicationVersion":"6.0.0",
"serverDate":"2023-04-16T11:11:21+00:00",
"ticket":"839ecda45f6449a8869747a80c26b2d2",
"applicationProvider":"CSB",
"metadata":null,
"status":"SUCCESS",
"mode":"TEST",
"serverUrl":"https://epaync.nc",
"_type":"V4/WebService/Response",
"answer":{
"operationSessionId":"30641640cba14eab8e6766094fd201da",
"operationUrl":"https://epaync.nc/api-payment/V4/Charge/Public/Authenticate/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname",
"_type":"V4/PCI/Authentication/AuthenticationSessionResponse"
}
}
Dans l'exemple :
answer.operationSessionId
: "30641640cba14eab8e6766094fd201da" answer.operationUrl
: "https://epaync.nc/api-payment/V4/Charge/Public/Authenticate/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"
Une fois la session d'authentification créée, vous devez initialiser la librairie JavaScript puis appeler la méthode authenticate
.
Il est recommandé de rajouter un indicateur visuel de chargement lors de cet appel.
// définition de la class javascript
class KrAuthenticate {
constructor(publicKey,options)
authenticate(operationUrl)
}
NOM | DESCRIPTION | requis |
publicKey | Clé publique de TEST ou de PRODUCTION de la boutique.
Plus d'infos : **3 ème clé** du tableau des clés d'API REST. | Oui |
options | Elément du DOM dans lequel sera affichée la fenêtre d'authentification (facultatif). | Non |
Vous pouvez aussi faire apparaître la fenêtre d'authentification dans un autre élément du DOM grâce à l'attribut element
du paramètre facultatif options
.
- Sans élément DOM (conseillé) :
const krAuthenticate = new KrAuthenticate("15578053:testpublickey_1xhxA8MgmKyFJJK8fS7EaNRPAHDJFTv9AzlF6ue2ZJU8o");
const krAuthenticate = new KrAuthenticate("15578053:testpublickey_1xhxA8MgmKyFJJK8fS7EaNRPAHDJFTv9AzlF6ue2ZJU8o", {
element: document.getElementById("id-challenge-element")
});
Dans cet exemple, l' id de l'élement du DOM est : id-challenge-element
.
Utilisez le champ operationUrl
généré lors de l' appel PCI/Authentication/CreateSession (étape 2).
Exemple :
answer.operationUrl
: "https://epaync.nc/api-payment/V4/Charge/Public/Authenticate/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"
<!-- import JS -->
[...]
<script src="/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
[...]
<form action='javascript:authenticateSession()'>
<button id='submitButton' type='submit' class='btn btn-primary'>Authenticate</button>
</form>
[...]
<script>
// instantiate library
const krAuthenticate = new KrAuthenticate('15578053:testpublickey_1xhxA8MgmKyFJJK8fS7EaNRPAHDJFTv9AzlF6ue2ZJU8o');
// Callback removing the overlay
function myCallback(data) {
document.getElementById('overlay').remove();
}
// this is an example of overlay with a bootstrap spinner
function buildOverlay() {
let overlay = document.createElement('div');
overlay.setAttribute('id', 'overlay');
overlay.style.backgroundColor = '#D3D3D3';
overlay.style.height = '100%';
overlay.style.position = 'absolute';
overlay.style.top = '0';
overlay.style.opacity = '0.90';
overlay.style.width = '100%'
overlay.classList.add('d-flex', 'justify-content-center', 'flex-column', 'align-items-center');
overlay.innerHTML = `
<div class="spinner-border" role="status">
<span class="sr-only">Loading...</span>
</div>
`;
document.body.appendChild(overlay);
}
// Main function triggered by button
function authenticateSession() {
document.querySelector('#submitButton').disabled = true;
buildOverlay();
krAuthenticate.authenticate("https://theUrlFromThePciCall", myCallback);
}
</script>
La librairie JavaScript se charge d'exécuter toutes les actions nécessaires à l'authentification.
Ci-dessous une liste de cas possibles :
Le résultat de l'authentification sera automatiquement posté vers l'URL de notfication transmise dans l'appel au Web Service PCI/Authentication/CreateSession (champ ianTargetUrl
).
Ce résultat contient les données nécessaires à la demande d'autorisation comme dans l'exemple avec le CAVV.
La durée de la session d'authentification est fixée à 10 minutes.
Au bout de ce délai, il est recommandé de faire un appel au Web Service PCI/Authentication/GetSession pour obtenir le résultat de l'authentification.