3DS 2.0

What is 3DS 2.0?

3D Secure 2.0, or 3DS 2.0, is the 3D Secure authentication protocol’s latest update. 3DS 2.0 allows issuing banks to verify credit card holders during the transaction process. This helps protect cardholders against fraud and transfers liability away from the merchants. 3DS 2.0 adds an extra layer of security to online credit and debit card transactions. 3D stands for “three domains.” The first is the card issuer, the second is the retailer receiving the payment, and the third is the 3DS infrastructure platform that acts as a secure third party for both the consumer and retailer.

How are 3DS 1.0 and 3DS 2.0 different?

Unlike its predecessor, 3DS 2.0 offers a new approach to user authentication through the use of user information provided during the checkout process. With 3DS 2.0, the user is “silently” authenticated using their billing or shipping information, resulting in frictionless security authentication. 3DS 2.0 not only adds an extra security layer to prevent fraud, but it improves the overall user experience by foregoing the verification challenge presented in 3DS 1.0 reducing the number of checkout bounces.

💡 IMPORTANT: To complete a transaction, we require a Billing and Shipping address included in every order and/or charge. For us to be able to improve our fraud prevention and help give your customers a seamless shopping experience, we strongly recommend you add at least a Billing address. Failure to .provide this information could result in a failed transaction once 3DS 2.0. is triggered.

How does 3DS 2.0 work?

Step 1: Customer data collection

The customer adds their shipping and billing information during the checkout process. This data is used to “silently” authenticate the user after having obtained their credit or debit card information.

If the bank triggering 3DS 2.0 determines the data provided by the user is enough to complete the authentication process, the checkout process will be completed without any additional friction and the user will be redirected to the retailer’s confirmation page. (See step 6)

However, if the data provided doesn’t qualify for frictionless authentication, the user will be presented with the authentication challenge known in 3DS 1.0 shown in the following steps.

Step 2: Card information collection

The cardholder enters their unique credit or debit card data.

Step 3: Redirection to providers 3D secure pages

If 3DS 2.0 enrollment is confirmed the customer is then redirected to a 3D Secure page served by the card provider.

Step 4: Additional security authentication

On the provider’s website, the customer will be asked to enter their unique password or a one-time authentication code which will be emailed to their confirmed email address or sent to their confirmed number.

Step 4: Redirection to the merchant’s website

If the cardholder authentication went successfully the cardholder is then redirected back to a merchant’s website for payment confirmation.

Step 5: Página de confirmación del pago

Once back on the merchant’s site, the customer will receive confirmation of a successful payment.

How to implement 3DS?

First, you need to login into the Cash portal using your credentials.
From the menu, navigate and select the Developer menu.
Enter the return URL where the customer is going to be redirected once the 3DS 2.0 challenge is completed.
The 3D 2.0 Secure return URL is going to appear in the list here, remember that you can change it at any time.
Now you can create a Charge using the Transaction endpoint. As explained earlier 3DS 2.0 works with additional information such as the customer’s name, phone, email, billing, and shipping information to validate user identity and only challenges the user with a 3DS prompt if more verification is needed. , tion. To ensure that your customers have a frictionless experience with 3DS, please send the customer’s name, phone, email, billing and shipping information. If shipping information is not provided Hola Cash will use the provided billing information as shipping information.
1. Billing and Shipping information can be provided when you create an order or when you create a charge. The API fields are billing_details and shipping_details.
2. Each billing_details or shipping_details has an address,contact, and name field. It is important that you provide at least the following information when providing billing_details and shipping_details
If you use a hola_cash_payment_token as a payment credential and have provided the consumer_details, then Hola Cash will use that information as billing_details. If you still provide billing_details when creating a charge then the providedbilling_details will override the information stored at Hola Cash for the hola_cash_payment_token
If there is a need for the customer to complete the 3DS 2.0 Challenge, you will get a 400 response with the pending status, and the detail.code indicating action_required. In the detail.additional_details.action will be set to 3ds_authenticate indicating that the customer needs to be authenticated using 3DS and detail.additional_details.redirect_url points to the URL that the customer should be redirected to complete authentication.
Once the authentication process is completed, the customer will be redirected to the URL set in step 3. The Hola Cash Transaction ID is also provided as the query parameter TID. You can use the Transaction ID to check the transaction status using the get transaction details.
At the same moment, a 3DS 2.0 authentication is successful, a webhook with a successful charge is sent to the defined webhook URL (for more info check the Webhook Tutorial), if the 3DS 2.0 Authentication fails, then a webhook with the charge "failed" is sent. You can always use these webhooks to trigger specific workflows in your app.

How to test 3DS 2.0 transactions

Before moving into a production environment, we recommend you test functionality first. For this, we have a Sandbox environment available on the Widget & API from Hola Cash. To access Sandbox you need to use your Sandbox keys when calling the API or setting up the Widget. In 3DS 2.0 transactions, the Sandbox environment has some details. Before starting we recommend you see testing cards for this procedure.

If you take a look at step 6 for the 3DS 2.0 implementation we can see that the API response error contains a URL. This URL is a redirect URL for the users, when they are redirected to this page they'll be able to complete their authentication. In the Sandbox environment, this URL will redirect users to the testing 3DS 2.0 environment, here you'll be able to visually choose the flow of the transaction. By clicking any of the two buttons the preconfigured redirect URLs from the portal are generated, then an event will be triggered to any configured webhook URL.

Remember that to trigger a 3DS 2.0 authentication, you must send the amount mentioned in the testing cards section.

You can quickly test the behavior via Curl, remember to replace the call with your own credentials.

Token Creation

curl --location --request POST 'https://sandbox.api.holacash.mx/v2/tokenization/payment_token' --header 'X-Api-Client-Key: <PASTE YOUR SECRET API KEY>' --header 'X-Cash-Anti-Fraud-Metadata: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2MTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ==' --header 'Content-Type: application/json' --data-raw '{ "credential": { "payment_method": { "method": "credit_or_debit_card" }, "credit_or_debit_card": { "card_number": "4000000000003063", "expiration_month": "12", "expiration_year": "2034", "card_validation_code": "123" } }, "consumer_details": { "contact": { "email": "richa@abc.com" }, "name": { "first_name": "Test", "second_first_name": "Hola", "first_last_name": "Cash", "second_last_name": "User" } } }'

Charge creation (replace payment_token)

curl --location --request POST 'https://live.api.play.holacash.mx/v2/transaction/charge' --header 'X-Api-Client-Key: <PASTE YOUR PUBLIC API KEY>' --header 'X-Cash-Anti-Fraud-Metadata: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ====' --header 'Content-Type: application/json' --data-raw '{ "description": "This is a test description", "amount_details": { "amount": 3071, "currency_code": "MXN" }, "payment_detail": { "credentials": { "payment_method": { "method": "pay_with_holacash_payment_token" }, "holacash_payment_token": { "payment_token": "<PASTE YOUR PREVIOUSLY CREATED TOKEN>" } } }, "consumer_details": { "external_consumer_id": "your_consumer_id", "contact": { "id": "1234", "email": "test_abc@abc.com" }, "name": { "first_name": "Snoop", "second_first_name": "the", "first_last_name": "Doggy", "second_last_name": "Dog" } }, "billing_details" : { "contact": { "email": "test_user@example.com" }, "name": { "first_name": "Test", "second_first_name": "Hola", "first_last_name": "Cash", "second_last_name": "User" }, "address" : { "address_line_1" : "First line of address", "address_line_2" : "Unit number", "locality" : "CDMX", "region_name_or_code" : "CX", "postal_code" : "11503", "country_code" : "MEX" } }, "shipping_details" : { "contact": { "email": "test_user@example.com" }, "name": { "first_name": "Test", "second_first_name": "Hola", "first_last_name": "Cash", "second_last_name": "User" }, "address" : { "address_line_1" : "First line of address", "address_line_2" : "Unit number", "locality" : "CDMX", "region_name_or_code" : "CX", "postal_code" : "11503", "country_code" : "MEX" } }, "processing_instructions": { "auto_capture": false } }'

Using the Checkout Widget

See the section: “Create an Order” in the Quickstart guide for the Checkout Widget