3DS 2.2 BRW

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

{
    "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
}

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

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

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

Le champ threeDSServerTransId est disponible pour un seul appel uniquement, si vous l'utilisez une seconde fois vous recevrez un code HTTP 400

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://urlduclient.sitexample.com: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 signification :

Pas d'authorisation (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.

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

Authorisation 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 :

{
    "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"
}

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

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

4) 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 ».
• Afin d'avoir un webhook sur votre serveur (backend) à la fin du challenge, l'URL configurée dans le paramètre notificationURL sera appelée.

Voici ce que vous aurez dans notre environnement de test pour l'affichage du Challenge OTP (dans des conditions de PROD, la fenetre 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é

5) REPONSE

• A l'issue du challenge, les informations concernant celui-ci sont disponibles dans la variable "finalCresValue"
• Pour recuperer les informations de cette valeur base 64 il faut la decoder, 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 appelez GET /results afin de connaitre les données necessaire 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é.

6) RESULTAT

•    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"
}

7) Transaction

• Les données suivantes sont nécessaire afin de valider une transaction en 3DS 2.0 :
  • 3ds[threeDSServerTransID] = threeDSServerTransID
  • 3ds[status] = transStatus
  • 3ds[cavv] = authenticationValue
  • 3ds[eci] = eci
  • 3ds[xid] = Paramètre Custom destiné au 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'