Start ThreeDS

Function startThreeDs in Carat's JavaScript#

This call is essential to activate 3DS 2.0 authentication, check if the cardholder's card number is within the supported card range for authentication, and, when necessary, initiate the 3DS Methods flow to capture additional browser information, aiming to facilitate risk-based decision-making (RBA - Risk-Based Analysis), increasing the chances of obtaining a challenge-free authentication.

To use the startThreeDs function, simply add the JavaScript payment file with 3DS 2.0 authentication and the div tag to the checkout page. Both the file and the div tag are essential to ensure that the startThreeDs function works correctly.

Script JS#

URL for Production environment:

https://esitef.softwareexpress.com.br/js/esitefauthenticatepayment-1.0.min.js

URL for Homologation environment:

https://esitef-homologacao.softwareexpress.com.br/js/esitefauthenticatepayment-1.0.min.js

Below is the mandatory div tag for the operation of the 3DS method.

<div id="divThreeDsMethodData"></div>

Card number field#

In addition to the items mentioned earlier, it is crucial that the card number field has the specified class below:

Parameter	Description	Format	Mandatory
`esitef-cardnumber`	Buyer's card number (PAN).	< 19 N	YES

Example

<input type="number" id="card-number" maxlength="16"  class="esitef-cardnumber">

Calling the startThreeDS function in Carat JavaScript#

When the buyer enters the card number on the screen, it is possible to create a JavaScript event or a button that triggers the startThreeDS function. The implementation of the event or button does not follow a specific rule, as long as it is triggered after filling in the card number. When calling the startThreeDS function, it is essential to provide a request with the following fields as arguments:

Parameter	Description	Format	Mandatory
`nit`	Transaction identifier in Carat. Field `nit` received in the transaction creation step.	= 64 AN	YES
`payToken`	Field `pay_token` received in the transaction creation step.	= 66 AN	YES
`merchantId`	Store code in Carat. Production and certification codes will be different.	< 15 N	YES
`locale`	Language of messages returned in validation errors (callback "onInvalid"). It can take the following values: `pt` - Portuguese `en` - English `es` - Spanish If the locale is not sent, `pt` will be used.	= 2 A	NO
`authorizerId`	Code of the authorizer in Carat. Learn more.	< 3 N	NO
`onSuccess`	Callback function that will be called after a successful call to the `startThreeDS` function in Carat. This function receives as an argument the response of the `startThreeDS` function described in - Response of success and failure callbacks.	F	YES
`onFailure`	Callback function that will be called after an unsuccessful call to the `startThreeDS` function in Carat. This function receives as an argument the response of the `startThreeDS` function described in - Response of success and failure callbacks.	F	YES
`onInvalid`	Callback function that will be called after a JavaScript validation error. This function receives as an argument the list of errors described in - Response of validation error callback.	F	YES

Response of Success and Failure Callbacks#

The onSuccess and onFailure callback functions receive an object as an argument containing information regarding the response of the startThreeDs function. Below are the descriptions of these fields:

Parameter	Description	Format
`code`	Carat response code. Any code other than 0 (zero) indicates failure. For more information, refer to the Response Codes.	< 4 N
`message`	Carat response message.	< 500 AN
`authorizer_id`	Authorization code in Carat. Learn more. `(só em caso de sucesso)`.	< 3 N

Validation error callback response.#

The onInvalid callback function receives, as an argument, a list of validation error objects containing the following fields:

Parameter	Description	Format
`field`	Name of the field with an error.	< 30 AN
`cause`	Error message.	<100 AN

Example#

Below is an example of a page integrated with Carat's JavaScript payment:

To use this example, don't forget to set the {{url}} variable with the value.
esitef-homologacao.softwareexpress.com.br

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://{{url}}/js/esitefauthenticatepayment-1.0.min.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            document.getElementById('card-number').addEventListener('input', function() {
                var valor = this.value;

                valor = valor.replace(/\s/g, '');

                if (valor.length === 16) {
                    threedMethod();
                }
            });
        });

        function threedMethod() {
            var request = {
                onSuccess: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.authorizer_id);
                },
                onFailure: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                },
                onInvalid: function(errors) {
                    for (var i = 0; i < errors.length; i++) {
                        console.log(errors[i].field);
                        console.log(errors[i].cause);
                    }
                },
                nit: '183479a213bcd653909a959907817f452a7e36846bd922b6c891804ae4118b16',
                payToken: '955d19823f1e3f74e4c6d57e895ed32473d929669ea1ef5fc0e18783265c34e301',
                merchantId: 'XXXXXXXXXXXX',
                locale: 'pt',
                authorizerId: '2'
            };
            startThreeDs(request);
        }
    </script>
  </head>

  <body>
    <form method="POST">
        <input type="text" id="card-number" maxlength="16"  class="esitef-cardnumber">
    </form>
  </body>
</html>