Skip to main content

Cards with 3DS 2

3DS 2 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, 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 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 overviewchevron_right

Requirements​

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

Authentication methods​

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

  1. EBANX SDK Authentication - The integration utilizes the EBANX.js Client SDK for authentication. The data obtained is subsequently included in the payment request payload transmitted via the EBANX Direct API. This approach is favored for delivering a superior shopper experience.
  2. EBANX Direct API Authentication - In this integration, EBANX provides a redirect URL to facilitate the shopper's authentication process via the Direct API. This method offers a streamlined approach for initiating the authentication service.
  3. External Authentication - Authentication is managed through an external Third-Party Authenticator. The authentication data obtained is subsequently incorporated into the payment request, which is processed using the EBANX Direct API.

Choose authentication method​


Follow the steps below to integrate 3DS 2 using EBANX SDK 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 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.


Resources​

Use the following resources when testing 3DS 2 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 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: