Skip to main content
Cards with 3DS 2.0

3DS 2.0 at EBANX is a security feature designed to add an extra layer of authentication for card transactions, enhancing protection against fraud and improving compliance with international security standards. With 3DS 2.0, cardholders go through a streamlined verification process, where additional checks are performed without disrupting the user experience. This method provides risk-based authentication, meaning only transactions flagged as high-risk may require customer interaction, making the process smoother for most users. EBANX’s 3DS 2.0 implementation supports a variety of card networks and integrates directly with your payment flow.

For more information and availability, refer to the
3D Secure 2.0 overviewchevron_right

Requirements​

  • API credentials - Make sure you have your EBANX integration key. If not, complete the Merchant Signup Form.

Authentication methods​

There are two methods to authenticate a payment when using 3DS 2.0:

  1. EBANX authentication - The authentication is performed via the EBANX.js Client SDK, and the resulting data is included in the payment request using our EBANX Direct API.
  2. External authentication -Authentication is handled through a 3rd Party Authenticator, and the resulting data is added to the payment request using our EBANX Direct API.

Choose authentication method​


Follow the steps below to integrate 3DS 2.0 using EBANX Authentication.

  1. Integrate the SDK into your webpage

    Add the EBANX.js SDK to your webpage using the following script:

    <script type="text/javascript" src="https://ebanx-js.ebanx.com/latest/dist/ebanx.min.js"></script>

    Initialize the SDK with your merchant configuration:

    EBANX.init({
      publicIntegrationKey: '{your_public_integration_key}',
      country: '{country_code_here}',
      mode: 'test',
    });

    Parameters​

    FieldDescription
    publicIntegrationKeyMerchant's public integration key
    countryCustomer country code.
    2-digit String
    International standard - ISO 3166-1 alpha-2
    modetest or production

  2. Define your options

    Create orderInformation, paymentInformation and personalIdentification with the following fields:

    // Order Information
    const orderInformation = {
      amountDetails: {
        totalAmount: '10.04',
        currency: 'BRL',
      },
      billTo: {
        address1: 'Rua Estanislau Szarek',
        administrativeArea: 'PR',
        country: 'BR',
        email: '1584023172@exemplo.com.br',
        homePhone: '41999999999',
        locality: 'Curitiba',
        postalCode: '81315380',
        mobilePhone: '41999999999',
      },
    };

    // Payment Information
    const paymentInformation = {
      card: {
        number: '4000000000001000',
        expirationMonth: '12',
        expirationYear: '34',
        holderName: 'JOAO DA SILVA',
      },
      paymentMethod: 'creditcard', // Set to 'creditcard', or 'debitcard'.
      dataOnly: true, // Set to true for Data Only authentication flow.
    };

    // Personal Identification
    const personalIdentification = {
      id: '97370192024',
      type: 'CPF',
    };


    Data-Only flow.

    The 3D Secure (3DS) Data-Only flow enhances online transaction security and boosts authorization rates by eliminating the need for user authentication, ensuring a seamless customer experience. In this process, merchants provide the additional data required by 3DS 2.0 directly to card schemes (e.g., Mastercard, Visa). These schemes incorporate the risk data into the authorization message, enabling issuers to make more informed and confident decisions. use the paymentInformation.dataOnly parameter to enable this workflow.

  3. Authenticate your payment request

    Invoke Authentication Method​

    Invoke EBANX.threeDSecure.authenticate using objects from previous step.

    const options = {
      orderInformation,
      paymentInformation,
      personalIdentification,
    };

    EBANX.threeDSecure.authenticate(options)
      .then((authenticationData) => {
        // Use authenticationData in your `Create Payment` API request.
      })
      .catch((error) => {
        // Handle Errors
      });

    Method Response​

    The EBANX.threeDSecure.authenticate method returns a Promise object, so it's important to handle the asynchronous call properly, typically by using a .then() callback or async/await. A successful authentication response will contain the following fields, though the values may vary with each authentication:

    // authenticationData

    {
      threeds_eci: "05",
      threeds_cryptogram: "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
      threeds_xid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA",  
      threeds_version: "2",                       
      threeds_trxid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA" 
    }

    Method Failure​

    If authentication fails, you can simply retry the request. Common causes include:

    • Invalid customer input
    • Issuer unavailable
    • Communication issue

  4. Create a payment request

    Use the EBANX Direct API to create a payment request.

    Examples:​

    -Using Spread Operator:​

    // payment.card object in your EBANX Direct API request

    "payment" : {
       "card": {
          "card_number": 4000000000001000,
          "card_name": "JOAO DA SILVA",
          "card_due_date": "12/2034",
          "card_cvv": "123",
          ...authenticationData // Spread Operator
       }
    }

    Older Javascript:​

    // payment.card object in your EBANX Direct API request

    "payment" : {
      "card": {
          "card_number": 4000000000001000,
          "card_name": "JOAO DA SILVA",
          "card_due_date": "12/2034",
          "card_cvv": "123",
          "threeds_eci": "05",
          "threeds_cryptogram": "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
          "threeds_xid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA",    
          "threeds_version": "2",                          
          "threeds_trxid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA"  
          } 
    }

    Important

    In cases where authentication isn't required, such as with Caixa debit cards, EBANX.threeDSecure.authenticate returns an empty object. To avoid issues, we recommend using a spread operator when adding the response to your payment. This ensures that if the object is empty, it won't disrupt your payment process.


  5. Congratulations!

    You have completed the necessary steps to create a card payment using 3DS 2.0.


Resources​

Use the following resources when testing 3DS 2.0 in your sandbox environment.

Credic Card Icon

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right
Debit Card Icon

ECI responses

Click here to access Electronic Commerce Indicator (ECI) responses.

Click to explorechevron_right


Troubleshooting​

3DS 2.0 Error Codes

When an error occurs, EBANX responds with a JSON object containing detailed error information.

Code
Error Message
Description
BP-3DS-1For 3DS 2.0 transactions, Parameter public_integration_key not informedParameter public_integration_key not informed.
BP-3DS-2For 3DS 2.0 transactions, Invalid public integration keyInvalid public integration key.
BP-DR-130For 3DS 2.0 transactions, field payment.card.threeds_cryptogram is requiredThe Cryptogram field was not filled.
BP-DR-131For 3DS 2.0 transactions, field payment.card.threeds_eci is requiredThe ECI field was not filled.
BP-DR-132For 3DS 2.0 transactions, field payment.card.threeds_cryptogram and payment.card.threeds_eci are requiredThe Cryptogram and ECI fields were not filled.
BP-DR-138Parameter payment.card.threeds_trxid is mandatory for 3DS Data OnlyThe Directory Server Transaction ID was not filled and it is mandatory when you are sending a transaction with 3DS Data Only Authentication
BP-DR-139Parameter payment.card.threeds_version is invalid. The valid values are 1 (for 3DS 1.0) and 2 (for 3DS 2.0)The ThreeDSecure version sent is invalid. You should use 1, for 3DS 1.0, or 2 for 3DS 2.0

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: