Version: current

Cards with 3DS 2

About this guide

This page explains how to add 3DS 2, to your existing Direct API integration. Direct API integration is basically the same for all payment methods, only varying the payment_type_code and some additional required fields.

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. Credit Cards or Debit Cards enabled in your EBANX Dashboard.

How it works

There are two options you can use to authenticate a payment using 3DS.

  1. EBANX Authentication: In this method, the authentication is done through the EBANX.js Client SDK and the resulting data is added to the payment using our EBANX Direct API.

  2. External Authentication: In this method, the authentication is done through a 3rd Party Authenticator and the resulting data is added to the payment using our EBANX Direct API.

We'll cover the steps of both methods in this guide.

3D Secure 2 with EBANX Authentication

Availability

Brazil 🇧🇷 South Africa 🇿🇦 India 🇮🇳

  1. Add EBANX.js to your webpage

    Our client SDK enables you to securely collect payment information from your customers. Add the following script to your webpage:

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

    And initialize it with your Merchant's Configuration:

    EBANX.init({
    publicIntegrationKey: 'your_integration_key_goes_here',
    country: 'br',
    mode: 'test',
    });
  2. Create an object with your order information

    Create an object with with the following fields:

    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',
    },
    };
  3. Create an object with your payment information

    Create an object with with the following fields:

    note

    The paymentMethod must be debitcard for Debit Cards and creditcard for Credit Cards.

    note

    The 3D Secure (3DS) Data-Only flow is designed to enhance the security and authorization rates of online transactions without requiring user authentication, providing a frictionless experience for the customer. In this model, merchants submit the same additional data required by 3DS 2.0 directly to the card schemes (e.g., Mastercard, Visa), and the schemes include their risk data within the authorization message, helping issuers make more informed decisions.

    const paymentInformation = {
    card: {
    number: '4000000000001000',
    expirationMonth: '12',
    expirationYear: '34',
    holderName: 'JOAO DA SILVA',
    },
    dataOnly: true,
    };
  4. Create an object with your customer's information

    Create an object with with the following fields:

    const personalIdentification = {
    id: '97370192024',
    type: 'CPF',
    };
  5. Authenticate your payment request

    Call the EBANX.threeDSecure.authenticate function using the objects created in steps 2, 3 and 4. During this step, if deemed necessary by the issuing bank, additional authentication will be requested.

    note

    If your payment required authentication and it failed, you can send an authentication request again. An authentication can fail because of an invalid input from customers during a challenge, issuers unavailability and communication issues.

    const options = {
    orderInformation,
    paymentInformation,
    personalIdentification,
    };
    EBANX.threeDSecure
    .authenticate(options)
    .then((authenticationData) => {
    // use the authenticationData object to fullfil your payment
    })
    .catch((error) => {
    // handle any errors that can happen
    });

    EBANX.threeDSecure.authenticate returns a Promise object, so, make sure you handle the asynchrounous call properly by using a callback function. A successful authentication response contains the following fields. The values will vary for each authentication:

    //The authenticationData object created in the previous step will have the following fields:
    {
    threeds_eci: "05",
    threeds_cryptogram: "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
    threeds_xid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA", //This field is optional and might not be in every authentication
    threeds_version: "2", //This field is optional and might not be in every authentication
    threeds_trxid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA" //This field is optional and might not be in every authentication
    }
  6. Add the 3DS Authentication values to your payment

    Include the values acquired in Step 5 in the payments.card object in your Direct API call. For more information on our Direct API, click here!

    Important

    EBANX.threeDSecure.authenticate returns an empty object in cases where authentication was not necessary, Caixa debit cards for example. Because of that, we recommend adding the response using a spread operator. This way, if the object is empty, it won't interfere with your payment.

    //If you're using old Javascript syntax, the spread syntax will not work. So in this case you can set the card properties individually.
    "card": {
    "card_number": 4000000000001000,
    "card_name": "JOAO DA SILVA",
    "card_due_date": "12/2034",
    "card_cvv": 123,
    ...authenticationData //spread of the object returned by EBANX.threeDSecure.authenticate and passed to your successCallback function.
    }

    The payment_type_code must be debitcard for Debit Cards and creditcard for Credit Cards.

    "payment_type_code": "debitcard"
    "payment_type_code": "creditcard"

External Authentication

The main difference in this method is that you'll handle the process of generating the 3DS values through a 3rd party and simply add them to your payment request.

Availability

Brazil 🇧🇷, Mexico 🇲🇽, Colombia 🇨🇴

  1. Authenticate the payment using your External Authenticator

    The steps to perform the external authentication will depend on the provider of your choice.

    note

    Caixa's debit card is the only case where 3DS 2.0 is not required. For all other debit cards in Brazil 🇧🇷 the usage of 3DS 2.0 protocol is mandatory.

  2. Add the 3DS Authentication values to your payment

    Now that your payment has been authenticated, include the values acquired in Step 1 in the payments.card object in your Direct API call.

    "card": {
    "card_number": 4000000000001091,
    "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"
    }

    The payment_type_code must be debitcard for Debit Cards and creditcard for Credit Cards.

    "payment_type_code": "debitcard"
    "payment_type_code": "creditcard"
note

CAVV Mastercard: Must be send in base 64 format. The variable of Transaction ID must not travel in VISA trx´s, just in Mastercard trx´s

MasterCard

[
"MODE" => "PRD"
"ENTRY_MODE" => "MANUAL"
"RESPONSE_LANGUAGE" => "EN"
"CMD_TRANS" => "PREAUTH"
"MERCHANT_ID" => "8705233"
"USER" => "*****"
"PASSWORD" => "*****"
"TERMINAL_ID" => "87052331"
"AMOUNT" => "1.00"
"CARD_NUMBER" => "526777******5903"
"CARD_EXP" => "06/2031"
"SECURITY_CODE" => "***"
"CONTROL_NUMBER" => "132052366249"
"CUSTOMER_REF1" => "132052366249"
"CUSTOMER_REF5" => "EBANX"
"ECI" => "02"
"CAVV" => "kBMdsfyvu9+WFwBkZX8kg0hBZkZy"
"STATUS_3D" => "200"
"VERSION_3D" => "2"
"TRANSACTION_ID" => "117dd3e5-242a-47be-9a0e-a6d60f67be64"
]
note

CAVV VISA and XID: Must be send in hexa-decimal format. The variable of Transaction ID must not travel in VISA trx´s, just in Mastercard trx´s

Visa

[
"MODE" => "PRD"
"ENTRY_MODE" => "MANUAL"
"RESPONSE_LANGUAGE" => "EN"
"CMD_TRANS" => "PREAUTH"
"MERCHANT_ID" => "8705233"
"USER" => "*****"
"PASSWORD" => "*****"
"TERMINAL_ID" => "87052331"
"AMOUNT" => "1.00"
"CARD_NUMBER" => "407561******6927"
"CARD_EXP" => "10/2026"
"SECURITY_CODE" => "***"
"CONTROL_NUMBER" => "132052384617"
"CUSTOMER_REF1" => "132052384617"
"CUSTOMER_REF5" => "EBANX"
"ECI" => "05"
"XID" => "0002010731177600000000644842297500000000"
"CAVV" => "0002010731177600000000644842297500000000"
"STATUS_3D" => "200"
"VERSION_3D" => "2"
]

Test Scenarios

Below you can find test card numbers and other information to make sure your integration is working as planned! You can use any of the following test card numbers, a valid expiration date in the future, and any random CVV number, to create a successful payment.

  • CVV: Use any number with three digits, except for American Express whose CVV has four digits;
  • Expiration date (due date): Use any date in the future.
BrandCardScenario
visa4000000000001000Approved (3DS without Challenge)
visa4000000000001091Insufficient Funds (3DS with Challenge)
visa4000000000001042Invalid Card or Card Type (3DS with Challenge)
visa4000000000001109Invalid Card or Card Type (3DS without Challenge)
mastercard5200000000001096Approved (3DS with Challenge)
mastercard5200000000001005Insufficient Funds (3DS with Challenge)
mastercard5200000000001013Invalid Card or Card Type (3DS with Challenge)
mastercard5200000000001104Invalid Card or Card Type (3DS without Challenge)
maestro6759411100000008Approved (3DS without Challenge)
elo6505050000001000Approved (3DS without Challenge)

3DS ECI Response

MasterCard

ECILiability
01Card scheme authentication, liability on issuer bank
02Issuer bank authentication, liability on issuer bank
04Data Only, liability on merchant
00Authentication failed, liability on merchant

Other card schemes

ECILiability
06Card scheme authentication, liability on issuer bank
05Issuer bank authentication, liability on issuer bank
07Authentication failed, liability on merchant

API Error codes for 3DSecure

Below you can find the error codes related to 3DSecure fields:

    Error codes, messages and descriptions
    Code
    Error message
    Description
    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

    Live Sample

    Getting help

    We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

    • If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
    • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
    Last updated on by José Cristiano de Sousa