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

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.

   const paymentInformation = {

   card: {

   number: '4000000000001000',

   expirationMonth: '12',

   expirationYear: '34',

   holderName: 'JOAO DA SILVA',

   },

   paymentMethod: 'creditcard',

   };

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.

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"

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.

Brand	Card	Scenario
visa	4000000000001000	Approved (3DS without Challenge)
visa	4000000000001091	Insufficient Funds (3DS with Challenge)
visa	4000000000001042	Invalid Card or Card Type (3DS with Challenge)
visa	4000000000001109	Invalid Card or Card Type (3DS without Challenge)
mastercard	5200000000001096	Approved (3DS with Challenge)
mastercard	5200000000001005	Insufficient Funds (3DS with Challenge)
mastercard	5200000000001013	Invalid Card or Card Type (3DS with Challenge)
mastercard	5200000000001104	Invalid Card or Card Type (3DS without Challenge)
maestro	6759411100000008	Approved (3DS without Challenge)
elo	6505050000001000	Approved (3DS without Challenge)

3DS ECI Response

MasterCard

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

Other card schemes

ECI	Liability
06	Card scheme authentication, liability on issuer bank
05	Issuer bank authentication, liability on issuer bank
07	Authentication 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

search

Code arrow_downward	Error message arrow_downward	Description arrow_downward
BP-DR-130	For 3DS 2.0 transactions, field payment.card.threeds_cryptogram is required	The Cryptogram field was not filled.
BP-DR-131	For 3DS 2.0 transactions, field payment.card.threeds_eci is required	The ECI field was not filled.
BP-DR-132	For 3DS 2.0 transactions, field payment.card.threeds_cryptogram and payment.card.threeds_eci are required	The Cryptogram and ECI fields were not filled.
BP-DR-138	Parameter payment.card.threeds_trxid is mandatory for 3DS Data Only	The Directory Server Transaction ID was not filled and it is mandatory when you are sending a transaction with 3DS Data Only Authentication
BP-DR-139	Parameter 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

See the Pen by ferpa2012 (@ferpa2012) on CodePen.

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.