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:
- An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
- 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.
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.
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 🇮🇳
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',});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',},};Create an object with your payment information
Create an object with with the following fields:
note
The
paymentMethodmust bedebitcardfor Debit Cards andcreditcardfor 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,};Create an object with your customer's information
Create an object with with the following fields:
const personalIdentification = {id: '97370192024',type: 'CPF',};Authenticate your payment request
Call the
EBANX.threeDSecure.authenticatefunction 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.authenticatereturns 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 authenticationthreeds_version: "2", //This field is optional and might not be in every authenticationthreeds_trxid: "AAIBAkl0NwmHglFBAXQ3AAAAAAA" //This field is optional and might not be in every authentication}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.authenticatereturns 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_codemust bedebitcardfor Debit Cards andcreditcardfor 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 🇨🇴
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.
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_codemust bedebitcardfor Debit Cards andcreditcardfor 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
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
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:
Code | Error message | Description |
|---|---|---|
| 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
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.