3D Secure 2 is a new solution of authentification which restrict fraud and bring a better experience for the consumer. By agreggate and transmit the datas created by the context of shopping, the consumer will not be bothered by the frictions created by a strong authentification. The card emitter (the bank) will thus be in position to know if the consumer is the real person that paid.
Following, some explanations about the process which differ with the 3DS 1.0 :
Before, to create a 3DS sales, you used the checkEnrollement and obtained the response about if the card was 3DS or not. In the case the card was indeed 3DS, you received the informations required to help the consumers to authentificate at they bank.
You can see this subject is more complex with the 3DS 2.0.
We will show the more important steps of the process :
The great steps of 3D Secure 2.0 :
1) VERSIONING
2)3DS METHOD
3)3DS AUTHENTICATION
4) CHALLENGE
5) REPONSE
6) RESULTAT
All this process must take place on the same web page.
For a better understanding of the process, upward is a global schema. For the technical documentation please consult here.
Le 3DS2 possède deux types d'intégrations possible :
Represents the majority of 3DS 2 integrations.
It requires the authentication of the customer to verify that he is the legitimate owner of the card at the time of the transaction. It triggers a challenge if necessary to verify the identity of the cardholder (SCA).
3DS Requestor Initiated (3RI) Authentications, or Merchant Initiated Authentications when the cardholder is not present or participating.
3RI offers the ability to generate the necessary 3DS authentications without the client being involved. This allows to use an authentication previously generated with a client. It is used in the following recurring payment contexts : Payment in X times, Subscription, Refund, etc. .
You can download the sources here : 3ds2.zip
<Directory "/var/www/htdocs">
RewriteEngine on
RewriteBase "/var/www/htdocs"
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php [L,QSA]
</Directory>
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^.*$ /index.php [L,QSA]these libraries are necessary for the proper functioning of the 3DS 2.0 test form
APP_ENV=dev
HOST_CENTRALPAY_API_CORE='https://test-api.centralpay.net/v2/rest/'
POS_UUID='change_it'
API_USER='change_it'
API_PASSWORD='change_it'| Champ | Description |
|---|---|
| APP_ENV | In development, the code always uses the same IP address (8.8.8.8) In production, use the client's IP address |
| HOST_CENTRALPAY_API_CORE | Centralpay api url: "https://test-api.centralpay.net/v2/rest/" for test mode |
| POS_UUID | Uuid of the point of sale |
| API_USER | API account login |
| API_PASSWORD | API account password |
Once the configuration is done, the form can be used.
"Css" directory: includes the Bootstrap library to manage the layout of the form
"JS" directory: includes the jquery, boostrap and jquery.validate libraries to manage javascript calls, form validation, etc.
"Templates" directory: contains the files that manage the display of the form
"Vendor" directory: contains the libraries downloaded by composer
".env" file: form configuration file
"Composer.json" file: Composer configuration file
"Index.php" file: file containing all the actions used to manage the form.
When the form is loaded in your browser, the form displays the following :
Several test card numbers are provided :
| Numéro de carte | Nom de l'action | Description |
|---|---|---|
| 4000001000000091 | BROWSER_CHALLENGE | Challenge to be performed for the payment to be accepted |
| 4000001000000067 | AUTHENTICATED_BROWSER_FRICTIONLESS | Payment accepted without having to make the challenge |
| 4000001000000075 | NOT_AUTHENTICATED_BROWSER_FRICTIONLESS | Payment refused without having to make the challenge |
| 4000000000000002 | Pas dans le range | Payment accepted without having to make the challenge |
All the stages of the form are carried out on a single page (integrated Iframe mode).
In this example, the checks are basic (fields completed, validity of the email address) : there is no check on the data format for example
13DS Versioning
When the customer clicks on the "Submit" button, if the form data is valid, an ajax call is made to the following Centralpay API url: "3ds2/versioning"
Note : Only the card number is sent to the API.
Example of calling the api in the "index.php" file Tag ##API_VERSIONING##
23DS Method
Request made in the backend by the browser to the bank simultaneously with the authentication.
An Iframe calls the url returned by the "3ds2/versioning" API call.
This url corresponds to the element : " threeDSMethodDataForm.threeDSMethodData " returned by the API.
33DS Authentication
Request made in parallel with the 3DS Method.
Another Ajax call is addressed to the following url of the CentralPay API: "3ds2/authentication
Example of call of the api in the file "index.php" Tag ##API_AUTHENTICATION##
The information sent to the API concerns the client's browser :
Other values are also returned such as the following fields :
Based on this data, the api will return a transaction status ("transStatus").
For all other values, a 'challenge' will be required to validate the transaction.
If the client needs to perform a challenge, an Iframe submits a form to the url returned by the API when calling "3ds2/authentication".
This url corresponds to the value : acsURL
The only parameter sent is : crep which includes the value base64EncodedChallengeRequest
At the end of the challenge, the configured url (parameter notificationURL ) in the "3ds2/authentication" call is called.
43DS Challenge
The information about the challenge is available in the variable cres which is accessible with the POST method. This variable is a JSON data encoded in base 64.
To decode this value, the following functions can be used :
$retour = json_decode(base64_decode($_POST['cres']), true)If the value of the variable $retour['threeDSServerTransID'] is equal to Y or A then the client has completed the challenge correctly.
It is then necessary to call the following API url :
" 3ds2/results/'.$retour['threeDSServerTransID']”
Example of calling the api in the file « index.php » Tag ##API_3DS2_RESULTS##
This call will return all the information about the WBS made by the customer. This information will be needed to finalise the transaction.
To finalise this you need to call the API transaction object :
Example of calling the api in the file « index.php » Tag ##API_TRANSACTION##
Available parameters :
| Nom du champ | Description |
|---|---|
| currency | Currency of payment |
| amount | Amount in cents |
| endUserIp | Customer IP address |
| merchantTransactionId | Merchant transaction reference |
| pointOfSaleId | Uuid of the point of sale |
| browserUserAgent | Browser user agent |
| browserAcceptLanguage | Browser language |
| card[number] | Bank card number |
| card[cvc] | Cvc of the bank card |
| card[expirationMonth] | Month of expiry of the bank card |
| card[expirationYear] | Year of expiry of the bank card |
| card[holderName] | Name of the cardholder |
| order[cardholderEmail] | Customer email |
| card[holderEmail] | Customer email |
| order[firstName] | Customer's first name |
| order[email] | Customer email |
| 3ds[xid] | Unique identifier of the 3ds auto generated by the merchant site |
| 3ds[cavv] | AuthenticationValue received from the 3ds2/result call |
| 3ds[eci] | Eci is received from the 3ds2/result call |
| 3ds[status] | TransStatus received from the 3ds2/result call |
| 3ds[threeDSServerTransID] | The ID of the 3DS server received from the 3ds2/result call |
If the http return code of the transaction is equal to 200, then the transaction is valid.
Payment form
Challenge
Valeurs :
Frequently asked questions about 3-D Secure 2.0.
Are there any test cards to do 3DS2 transactions in a test environment?
CentralPay EMV® 3-D Secure supports 2 device channels : Browser-based (BRW) and 3DS Requestor Initiated (3RI).
The Browser flow (BRW) in EMV® 3-D Secure, is an enhanced flow compared to its predecessor. During a Browser flow, the 3DS Method is used to allow the ACS to obtain additional browser information before the authentication is started.
The 3DS Requestor Initiated (3RI) is used to confirm account information when the cardholder is not directly involved (e.g. confirm that an account is still valid in a subscription).
My transaction received the bank return code 5, what does this mean ?
My transaction received the bank return code 12, what does this mean ?
The transaction API returns a "Soft Decline" error, but the "threeDSServerTransID" parameter is the one returned by the cres.
How should we interpret this return and what should we do ?
My Versioning request returns a "404" error with the message "Card account number not found in card ranges from Directory Server".
What does this mean and what should I do?
The response from the Result query returned the transStatus to U.
How should we interpret this return and what should we do in this case?
The value U of transStatus in response to the result request means that the authentication or verification could not be done due to a technical problem or other problems.
On the side of the smart form during the challenge with the result request, only the values Y and A allow to validate the challenge and to continue the payment.
The other values make the challenge and the payment fail.
But in the case of a custom form the operation can be different, you can use the value U to make a new challenge attempt and if it fails again then the payment goes to 3DS1 or is refused, or to directly retry the payment in 3DS1 or consider it as a payment failure.
These different cases are possible to realize.
We submitted the form to the url returned by the authentication with the base64EncodedChallengeRequest.
But the client came back to our site without CRES but with an ERROR parameter containing the value "eyJ0aHJlZURTU...Mi4xLjAifQ==" and the "THREEDSSESSIONDATA" parameter which was empty.
How should we interpret this return and what should we do in this case?
As a reminder, all the steps of the form are done on a single page without redirection to a bank page or other.
This is done thanks to the Iframe solution.
The whole 3DS2.0 procedure is on the same page!
We received a 303 error: "acquirerBIN, acquirerMerchantID not recognized" when calling authentication.
How should we interpret this return and what should we do in this case?
On the authentication step, we got an error 203: "Validation of 3DS Requestor Authentication data failed.
Data element not in the required format or value is invalid" for the merchant.merchantName field.
How should we interpret this feedback and what should we do in this case?
When calling the 3DS2 function "authentication", the following error is returned in the "card data" key: "There is no unique source of card".
What does this mean?
Version 1 (most frequent) :
{
"threeDSServerTransID":"9cc6b33c-dd35-4fbd-81cd-fd9cf0aeed9c",
"threeDSMethodURL":"https://test-3dss-demo.centralpay.net/acs/3ds-method",
"threeDSMethodDataForm":{
"threeDSMethodData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0LTNkc3MuY2VudHJhbHBheS5uZXQvM2RzLzNkcy1tZXRob2Qtbm90aWZpY2F0aW9uLyIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOWNjNmIzM2MtZGQzNS00ZmJkLTgxY2QtZmQ5Y2YwYWVlZDljIn0="
},
"errorDetails": null
}
This response is returned when the bank needs the acs url in the authentication request.
Version 2 :
{
"threeDSServerTransID":"9cc6b33c-dd35-4fbd-81cd-fd9cf0aeed9c",
"threeDSMethodURL": null,
"threeDSMethodDataForm": null,
"errorDetails": null
}
This response is returned when the bank does not need the acs url in the authentication request.
The versioning returns a response where only "threeDSServerTransID" has a non-null value.