How to integrate 3DS with Checkout Bricks

In this documentation you will find all the necessary information to carry out the integration with 3DS with Checkout Bricks. For more information on how this type of authentication works, see 3DS 2.0.

The integration with 3DS results in an authentication process that is carried out through two flows: with or without Challenge, with Challenge being the additional steps that the buyer must take to guarantee their identity.

For low-risk transactions, the information submitted at checkout is sufficient, the flow proceeds transparently, and additional Challenge steps are not required. However, for high fraud risk cases, the Challenge is required to verify the buyer's identity, which increases the approval of card transactions.

The decision to include the Challenge or not depends on the card issuer and the risk profile of the transaction being carried out.

Below are the steps to integrate with 3DS.

1. After generating a payment intent using Card Payment Brick or Payment Brick, it is necessary to send, from your backend, a payment request to Mercado Pago through our APIs. Enabling the 3DS 2.0 stream is done by adding the three_d_secure_mode: 'optional' field to this request.

var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken("YOUR_ACCESS_TOKEN");

const paymentData = {
...req.body,
three_d_secure_mode: 'optional'
};

mercadopago.payment.save(paymentData)
  .then(function(response) {
    const { status, status_detail, id } = response.body;
    res.status(response.status).json({ status, status_detail, id });
  })
  .catch(function(error) {
    console.error(error);
  });

If it is not necessary to use the Challenge flow, the status field of the payment will have the value approved and it will not be necessary to display it, in this way, the payment flow will proceed normally.

For cases where Challenge is required, status will show the value pending, and status_detail will be pending_challenge.

Simplified response overview:

{
   "payment_id":52044997115,
   "status":"pending",
   "status_detail":"pending_challenge",
   "three_ds_info":{
      "external_resource_url":"https://acs-public.tp.mastercard.com/api/v1/browser_Challenges",
      "creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImJmYTVhZjI0LTliMzAtNGY1Yi05MzQwLWJkZTc1ZjExMGM1MCIsImFjlOWYiLCJjW5kb3dTaXplIjoiMDQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IS4wIn0"
   },
   "owner":null
}

2. To continue the flow and display the Challenge in a simplified way, it is recommended to integrate with the Status Screen Brick, informing the ID generated payment, in addition to the content of the three_ds_info object, which were returned by the payment API.

If you do not want to use the Status Screen Brick at this stage, we advise you to access the Deployment section in the Checkout API documentation, as additional steps will be needed to, for example, capture the event emitted when the Challenge is completed.

const renderStatusScreenBrick = async (bricksBuilder) => {
 const settings = {
   initialization: {
     paymentId: "<PAYMENT_ID>", // payment id to be displayed
     additionalInfo: {
       externalResourceURL: "<EXTERNAL_RESOURCE_URL>",
       creq: "<C_REQ>",
     },
   },
   callbacks: {
     onReady: () => {},
     onError: (error) => {
       console.error(error);
     },
   },
 };
 window.statusScreenBrickController = await bricksBuilder.create(
   "statusScreen",
   "statusScreenBrick_container",
   settings
 );
};
renderStatusScreenBrick(bricksBuilder);

The Status Screen Brick will display a transition indicating redirection and then the Challenge of the bank in question will be displayed.

The user must respond to the Challenge for the transition to be properly validated. It is worth noting that the Challenge experience is the sole responsibility of the bank in charge.

3. After solving the Challenge, the final result of the payment will be displayed according to the answer issued by the bank at the end of the Challenge.

Before going into production, it is possible to test the integration to ensure that the 3DS flow works correctly and that payments are processed without errors. This way, it avoids buyers from abandoning the transaction because they can't complete it.

To enable the validation of payments with 3DS, we provide a sandbox testing environment that returns simulated results solely for simulation and implementation validation purposes. To perform payment tests in a sandbox environment, it is necessary to use your test credentials and specific cards that allow testing the Challenge implementation with success and failure flows. The following table presents the details of these cards

In both flows (success and failure), the Challenge, which is a screen similar to the one shown below, must be displayed by the Status Screen Brick.

The provided verification code is for illustrative purposes only. To complete the test flow, simply click the Confirm button, and the Status Screen will display the final state of the payment.