3DS 2.2 BRW (paiement unitaire)

Estimated reading: 8 minutes

1. Intégration du 3DS 2.0

Tout ce processus doit se dérouler sur la même page web (ceci est une contrainte du process bancaire).

👉 Téléchargez les sources

1.1. Les grandes étapes du 3D Secure 2.0

👉 Consultez un exemple de formulaire de paiement CUSTOM intégrant le 3DS 2.0

1.2. Versioning

Cette étape consiste à adresser le PAN de la carte à l’API Centralpay.

Exemple de code Curl :

    curl -v POST 'https://test-api.centralpay.net/v2/rest/3ds2/versioning' \
    -h 'Content-Type: application/x-www-form-urlencoded' \
    -u 'doctest:4I9HJRTd' \
    -d 'acctNumber=4000001000000067'
  • En réponse :
    • Si la carte n’est pas 3DS 2.0, le versioning vous retournera une erreur 404. Cela signifie que la carte utilisée n’est pas enrôlée 3DS 2.0 et que la transaction ne peut pas se faire en 3DS 2.0
    • Si la carte est 3DS 2.0, vous recevrez un UUID identifiant l’opération jusqu’au résultat final + les données nécessaire pour réaliser le « 3DS Method » (URL + base64)

Deux réponses au Versionning sont possibles si la carte est 3DS 2.0 :

  • Version 1 (la plus fréquente) :
{
    "threeDSServerTransID":"7d031b8e-7fb7-4215-b866-eaacb395002f",
    "threeDSMethodURL":"https://test-3dss-demo.centralpay.net/acs/3ds-method",
    "threeDSMethodDataForm":{
        "threeDSMethodData":"eyJ0aHJlZURTTWV0aG9kTm90aWZ
        pY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0LTNkc3MuY2VudHJ
        hbHBheS5uZXQvM2RzLzNkcy1tZXRob2Qtbm90aWZpY2F0aW9
        uLyIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOWNjNmIzM2M
        tZGQzNS00ZmJkLTgxY2QtZmQ5Y2YwYWVlZDljIn0="
    },
    "errorDetails":null
}

Cette réponse est renvoyée quand la banque a besoin de l’acs url dans la requête de l’authentification.

Le process 3DS Method est alors nécessaire, vous pouvez passer au point 2 : 3DS METHOD.

  • Version 2 :
{
    "threeDSServerTransID":"7d031b8e-7fb7-4215-b866-eaacb395002f",
    "threeDSMethodURL": null,
    "threeDSMethodDataForm": null,
    "errorDetails": null
}

Cette réponse est renvoyée quand la banque n’a pas besoin de l’acs url dans la requête de l’authentification.
Le versioning renvoie une réponse où seul « threeDSServerTransID » possède une valeur non null.

Le process 3DS Method n’est alors pas nécessaire, vous pouvez passer au point 3 : 3DS AUTHENTICATION BRW.

1.3. 3DS METHOD

Lorsque le versioning renvoi les champs threeDSMethodURL et threeDSMethodDataForm en « Non Null », le process 3DS Method est alors nécessaire.

Cette fonction a pour but de poster la donnée base64 reçue du versioning vers l’ACS. Le formulaire iframe doit être réalisée par le navigateur client vers la banque simultanément avec l’authentification.

Il faut réaliser une iFrame cachée qui servira à poster la donnée base64 (threeDSMethodData) à l’URL reçue dans le versioning (threeDSMethodURL).

1.4. 3DS AUTHENTICATION BRW

L’appel devra être adressé vers l’url suivante de l’API CentralPay : « 3ds2/authentication »
Cette requête permet l’envoi des données contextuelles liées au porteur

Exemple d’appel (curl code) :

    curl --location --request POST 'https://test-api.centralpay.net/v2/rest/3ds2/authentication' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
    --data-urlencode 'threeDSServerTransID=7d031b8e-7fb7-4215-b866-eaacb395002f' \
    --data-urlencode 'cardTokenId=5b9nb5cf-4470-4e58-b690-dd8965860eb8' \
    --data-urlencode 'deviceChannel=02' \
    --data-urlencode 'messageCategory=01' \
    --data-urlencode 'purchaseAmount=1000' \
    --data-urlencode 'purchaseCurrency=EUR' \
    --data-urlencode 'threeDSRequestorAuthenticationInd=01' \
    --data-urlencode 'browserJavaEnabled=true' \
    --data-urlencode 'browserLanguage=fr-FR' \
    --data-urlencode 'browserColorDepth=24' \
    --data-urlencode 'browserScreenHeight=1052' \
    --data-urlencode 'browserScreenWidth=1853' \
    --data-urlencode 'browserTZ=120' \
    --data-urlencode 'browserIP=127.0.0.1' \
    --data-urlencode 'browserUserAgent=Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:68.0) Gecko/20100101 Firefox/68.0' \
    --data-urlencode 'browserAcceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
    --data-urlencode 'notificationURL=http://dev4.dev.centralpay.net:1101/requestor/challenge-notification' \
    --data-urlencode 'threeDSRequestorURL=https://www.centralpay.eu'

L’api va retourner un statut de transaction (« transStatus »), voici les valeurs et leurs significations :

Pas d’autorisation (ne pas faire la transaction) :

  • N = Non authentifié /Compte non vérifié. Transaction refusée
  • U = L’authentification/la vérification du compte n’a pas pu être effectuée. Problème technique ou autre, comme indiqué dans ARes ou RReq
  • R = Authentification/vérification du compte rejetée. l’émetteur rejette l’authentification/vérification et demande de ne pas tenter d’autorisation
  • I = Information seulement. Reconnaissance de la préférence du demandeur pour le défi 3DS

Autorisation sans challenge :  

  • Y = Vérification de l’authentification réussie
  • A = Traitement des tentatives effectué. Non authentifié/vérifié, mais une preuve de tentative d’authentification/vérification est fournie

Autorisation après challenge : 

  • C = Challenge requis. Une authentification supplémentaire est requise en utilisant le CReq/CRes
  • D = Challenge requis. Authentification découplée confirmée

Exemples de réponses possibles :

C = Challenge requis :

{
"threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
"transStatus": "C",
"acsURL": "https://test-3dss-demo.centralpay.net/acs/challenge",
"acsChallengeMandated": "Y",
"base64EncodedChallengeRequest": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU2MDFlYjQ0LTU2N2MtNDM4Ny05MmZjLWU2ZjIzMjJiODIyYiIsImFjc1RyYW5zSUQiOiI3ZTQzZDI4ZC00M2RkLTRmM2MtYTcwOS00YjZkZDVlZjc5Y2QiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
"contractId": "71602dd0-2790-4743-877b-e72530d7576d"
}

Le Challenge est nécessaire.

Y = authentification réussie :

{
    "threeDSServerTransID": "7d994177-32d8-43f7-87a4-3a3cd734cbfe",
    "transStatus": "Y",
    "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjEa",
    "eci": "02",
    "contractId": "71602dd0-2790-4743-877b-e72530d7576d"
}

Le Challenge n’est pas nécessaire.
Les champs requis au 3DS 2.0 sont dans la réponse (threeDSServerTransID, transStatus, authenticationValue (cavv), eci).

Note : Le xid n’est pas fourni, car il s’agit d’une référence libre pour les marchands.

N = Transaction refusée :

{
    "threeDSServerTransID": "6396b832-3e5b-4143-bde6-f5r1c1e47da0",
    "transStatus": "N",
    "eci": "00",
    "contractId": "258128f3-5db9-4235-918a-f1d786f67c29"
}

Transaction refusée.

1.5. Challenge

  • Lorsque la réponse de l’authentification est « C« , l’utilisateur doit effectuer un challenge, une Iframe doit alors soumettre un formulaire à l’url (acsURL) retournée par l’API lors de l’appel à « 3ds2/authentication »
  • Le seul paramètre envoyé est : creq qui comprend la valeur base64EncodedChallengeRequest qui provient de l’appel à « 3ds2/authentication »
  • A la fin du challenge, l’url configurée (paramètre notificationURL ) dans l’appel « 3ds2/authentication » est appelée

Voici ce que vous aurez dans notre environnement de test pour l’affichage du Challenge OTP (dans des conditions de PROD, la fenêtre affichée sera celle de l’ACS) :

Voici les OTP en environnement test :

  • 1234 retourne Y pour Challenge réussi
  • 4444 retourne A pour Challenge réussi
  • 1111 retourne N pour Challenge échoué
  • 2222 retourne R pour Challenge échoué
  • 3333 retourne U pour Challenge échoué

1.6. Réponse

  • À l’issue du challenge, les informations concernant celui-ci sont disponibles dans la variable « finalCresValue »
  • Pour récupérer les informations de cette valeur base 64 il faut la décoder, voici un exemple en php :
$retour = json_decode(base64_decode($_POST['cres']), true)
  • Si celui-ci est égal à Y ou A alors le client a effectué le challenge correctement et le paiement est autorisé, vous devrez alors appeler GET /results afin de connaitre les données nécessaire aux 3DS 2.0 pour votre transaction
  • Si le statut de transaction est égal à une autre valeur, alors le client n’a pas effectué le challenge correctement et le paiement est refusé

1.7. Résultat

  • Pour connaitre les données 3DS 2.0 à renseigner à la création d’une transaction 3DS 2.0, vous devrez adresser le threeDSServerTransID de l’authentification 3DS 2.0 préalablement effectuée
  • Rappel : Si vous avez obtenu un transStatus à « Y » en réponse de l’authentification, les données 3DS 2.0 sont déjà contenu dans celui-ci

Appel :

curl --location -g --request GET 'https://test-api.centralpay.net/v2/rest/3ds2/results/{{threeDSServerTransID}}' \
--header 'Authorization: Basic e3tERUZBVUxUX1VTRVJ9fTp7e0RFRkFVTFRfUEFTU1dPUkR9fQ=='

Réponse :

{
    "threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
    "transStatus": "Y",
    "authenticationValue": "JAmi21makAifmwqo2120cjq1AAA=",
    "eci": "01"
}

1.8. Transaction

Les données suivantes sont nécessaires afin de valider une transaction en 3DS 2.0 :

  • 3ds[threeDSServerTransID] = threeDSServerTransID
  • 3ds[status] = transStatus
  • 3ds[cavv] = authenticationValue
  • 3ds[eci] = eci (Obligatoire si disponible)
  • 3ds[xid] = Paramètre Custom destiné aux marchands.

Exemple d’une transaction 3DS 2.0 :

curl --location --request POST 'https://test-api.centralpay.net/v2/rest/transaction' \
--header 'Origin: https://example.centralpay.net' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'currency=EUR' \
--data-urlencode 'amount=1500' \
--data-urlencode 'endUserIp=9.64.32.8' \
--data-urlencode 'endUserLanguage=ita' \
--data-urlencode 'merchantTransactionId=cpcg_12654de89ce44' \
--data-urlencode 'pointOfSaleId=1beb8574-cf4c-4b12-b065-d12b3f0eaa90' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (iPhone; CPU iPhone OS 16_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Mobile/15E148 Safari/604.1' \
--data-urlencode 'browserAcceptLanguage=it_IT' \
--data-urlencode 'paymentRequestBreakdownId=5485d7e6-60c3-753c-94d3-682eaaf9ae6e' \
--data-urlencode 'email=support@centralpay.eu' \
--data-urlencode 'receiptEmail=support@centralpay.eu' \
--data-urlencode 'capture=true' \
--data-urlencode 'cardTokenId=5b9nb5cf-4470-4e58-b690-dd8965860eb8' \
--data-urlencode 'order[cardholderEmail]=support@centralpay.eu' \
--data-urlencode 'order[firstName]=John' \
--data-urlencode 'order[lastName]=Doe' \
--data-urlencode 'source=EC' \
--data-urlencode '3ds[xid]=35876533346561303461' \
--data-urlencode '3ds[cavv]=JAmi21makAifmwqo2120cjq1AAA=' \
--data-urlencode '3ds[eci]=01' \
--data-urlencode '3ds[status]=Y' \
--data-urlencode '3ds[threeDSServerTransID]=7d031b8e-7fb7-4215-b866-eaacb395002f'
3DS 2.2 BRW (paiement unitaire) - PreviousAuthentification 3DS 2.2Next - 3DS 2.2 BRW (paiement unitaire)3DS 2.2 3RI (paiements récurrents)
CONTENU