How to Integrate 3DS with Checkout Bricks - Checkout Bricks - Mercado Pago Developers
Which documentation are you looking for?

Do not know how to start integrating? 

Check the first steps

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.

Important
To integrate with 3DS, certain requirements must be met. Before moving on to the next steps, review the Prerequisites section and make sure that all are met.

Integrate with 3DS

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.

javascript

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:

javascript

{
   "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
}
Important
The returned field three_ds_info contains the necessary information to continue the payment process if the status_detail is pending_challenge.
  1. 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.

javascript

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.

how-to-integrate-3ds

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.

Important
For security reasons, the payment will be rejected if the Challenge process is not started within 30 seconds after its creation. Therefore, it is important that the Challenge starts exactly after its generation.
  1. 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.

status-screen-Brick

Integration test

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

FlowNumberSecurity codeExpiration date
Successful Challenge5483 9281 6457 462312311/25
Unauthorized Challenge5361 9568 0611 755712311/25
The steps to generate the payment are the same as exemplified previously in this section.

Challenge

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.

bricks_sandbox

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.