This document gives you a general guide for how to implement 3-D Secure (3DS) using TabaPay's suite of tools.

Note: this guide is currently in progress. If you have suggestions or additional questions please feel free to use the community page.

📘

Make sure you have 3DS on your TabaPay Plan.

If you would like to implement 3DS, please make sure you have this service in your merchant agreement. If you are not sure, or would like to add it please contact the TabaPay team for more information.

Top-level structure

For an overview and required data please look at out 3DS integration overview.

🚧

3DS APIs do NOT process payment

3DS APIs only provide a way for you and the issuer to verify a customer's identity. In order to create a transaction you still have to call the create transaction API. The create transaction API has a body param for pullOptions. Within this object, you should find a 3DSecure object. Please look at the 3DSecure object and it's internal fields to know what information you will need to provide the createTransaction API.

Frontend integration details

🚧

Frontend does not communicate with our APIs directly

First thing to note, all contact with our API will have to go through your backend server. Any frontend application/service will have to communicate with your own servers. Your severs will then connect with the TabaPay API servers.

The details below are some suggestions to help with your own frontend integrations

Web integration

When integrating with 3DS please do not forget to collect the customer's device information. You can use the following guide to read more details: device date collection guide

SDK Mobile integration

Integrate 3DS into your native app using our iOS and Android SDKs. For more information, please read our 3DS SDK starter guide.

Backend integration details

📘

Important requirement

3DS 2.0 requires cardholder address as part of the authentication process at the issuer. If you're using Account ID as the payment instrument for 3DS, it must have billing address associated with it. So, please ensure you create accounts by providing address always.

"Required unless market or regional mandate restricts sending this information." - (EMV® 3-D Secure Protocol and Core Functions Specification v2.3.1.0, August 2022)

Steps in this guide

The following guide is broken down into these steps:

1. Create Account

2. Initialize API - Get the JWT

3. Device Data Collection (Frontend)

4. Lookup API - Authentication Request with the issuer

5. (Step up) - Challenge (Frontend)

6. (Step up) - Authenticate API - Verify the JWT you receive from the Challenge.

7. Create Transaction

Create account

In order to Initialize the 3DS API, you will need to provide either a customer's card information (please make sure you follow all PCI rules when handling card holder data), or a TabaPay accountID.

A TabaPay accountID is a Token provided by the TabaPay API to identify a particular end user's payment information. In order to create a Token simply call the Create Account API.

*If you are using the TabaPay PCI helpers, then you will have to use the Create Account API in order to use the 3DS API.

📘

3DS API will accept other payment methods in the future.

We are hoping to add other payment methods, like Apple Pay, to the 3DS Initialize API in the near future. However for now, you have to create a TabaPay Token through the Account API in order to use other payment methods.

Initialize API - Get the JWT

3DS utilizes a Json Web Token to store important information about the 3DS authentication. To start the authentication process you will need to generate this jwt and a 3dsID using the Initialize API.

Initializes a 3D Secure Card Authentication Request. This creates a jwt for 3D Secure Card Authentication.

If you are an ISO, you will need to specify a SubClientID.

URL
https://FQDN/v2/clients/ClientID/3ds/init

Merchant must connect with TabaPay’s 3D Secure Initialize

Notes:
For Clients who are an ISO, to specify your ClientID and a SubClientID, use the underscore character ("_") to separate the two values:   <ClientID>_<SubClientID>   where:

• ClientID is your unique 22-character string and
• SubClientID is an assigned 4, 6 or 8-digit value.

Request

Request Data:

Response

Status Codes:

Response Data:

Device Data Collection (Frontend)

Device Data Collection is an important part of 3DS 2.0. It allows you to send information to the issuer about the customer's device to kickstart the authentication process. In the ideal case, this information is key in reducing the rate at which your customer receives challenges. This step must be performed before you begin the lookup request in the next step. To complete this step, please use the following guide

🚧

Please do not forget to include this device data collection step in your frontend implementation.

Lookup API - Authentication Request with the issuer

📘

Important requirement

3DS 2.0 requires cardholder address as part of the authentication process at the issuer. If you're using Account ID as the payment instrument for 3DS, it must have billing address associated with it. So, please ensure you create accounts by providing address.

3D Secure Card Lookup.
If you are an ISO, you will need to specify a SubClientID.

URL
https://FQDN/v2/clients/ClientID/3ds/lookup

Notes:

For Clients who are an ISO, to specify your ClientID and a SubClientID, use the underscore character ("_") to separate the two values: <ClientID>_<SubClientID> where:

• ClientID is your unique 22-character string and
• SubClientID is an assigned 4, 6 or 8-digit value.

Lookup codes

The following documentation has the values you should use for the lookup call:

1. Authentication Indicator
2. Transaction Mode
3. Transaction Type
4. Product Code

Request

Response

Status Codes:

Response Data:

(Step up) - Challenge (Frontend)

Setting up the challenge flow:

When the issuer needs more information to authenticate a customer, they will ask for a challenge (also known as a step up). There are three common types of challenge:

1. One Time Passcode
2. Security question or "Knowledge Based Authentication (KBA)"
3. Out Of Band

The issuer decides which method to use, and as a merchant you will not have visibility into what is going on between the issuer and the customer. In order to know the result of the challenge, you will use an event listener:

Cardinal.on("payments.validated", function (data, jwt) {
    switch(data.ActionCode){
      case "SUCCESS":
      // Handle successful transaction, send JWT to backend to verify
      break;
     
      case "NOACTION":
      // Handle no actionable outcome
      break;
     
      case "FAILURE":
      // Handle failed transaction attempt
      break;
     
      case "ERROR":
      // Handle service level error
      break;
  }
});

Please note calling this function with the same namespace multiple times will result in a callback being triggered multiple times.

The response from the challenge will contain two fields: data and the jwt. You modify your payments.validated event to handle specific scenarios (specifically look at the data.actionCode)

Challenge Results:

📘

For more detailed information about ActionCodes

Please visit our 3DS challenge results page

The next step in the integration is to add logic to your payments.validated event to handle specific return values for CCA.

During the payments.validated is when you would call TabaPay's /authenticate endpoint, using the original 3dsID and the returned jwt from the CCA (a different jwt from the Initialize API)

After the authenticate API we will provide you with the UCAF, XID, ECI which you can use in the pullOptions of the CreateTransaction.

See more here: https://cardinaldocs.atlassian.net/wiki/spaces/CC/pages/98315/Response+Objects

Examples of what your customers might see: https://developer.visa.com/pages/visa-3d-secure/payment-flows-otp

Starting the challenge:

In order to initiate the challenge, you will need the processorTransactionID, challengeURL, and payload values from the lookup API response. The Cardinal.continue will display a modal window and automatically post the consumer's session over to the acs url for authentication.

Please note: AcsUrl = challengeURL

Using the example values

Cardinal.continue('cca',
{

AcsUrl:"https://example.cardinalcommerce.com/Example/creq.jsp",

Payload:"eyJtZXNzYsndfkjasdnfkjasnfkjdnaskWdlVmVyc2lv..."

 },

{

OrderDetails: {

TransactionId: "</lookup processorTransactionID here>"

}

});

Cardinal's Songbird.js will handle the entire challenge flow from here, and you will receive the authentication result after the challenge completes via the Cardinal.on("payments.validated"... function you previously setup.

(Step up) - Authenticate API - Verify the JWT you receive from the Challenge.

📘

The Authenticate API is called after the challenge is performed.

3D Secure Card Challenge Authentication.
If you are an ISO, you will need to specify a SubClientID.

URL
https://FQDN/v2/clients/ClientID/3ds/authenticate

Notes:
For Clients who are an ISO, to specify your ClientID and a SubClientID, use the underscore character ("_") to separate the two values: <ClientID>_<SubClientID> where:

• ClientID is your unique 22-character string and
• SubClientID is an assigned 4, 6 or 8-digit value.

Request

Response

Status Codes:

Response Data:

Create Transaction

👍

Almost done! Don't forget to create a transaction.

After the authenticate API we will provide you with the UCAF, XID, ECI which you can use in the pullOptions of the CreateTransaction.

Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.

Create Transaction pullOptions.3DSecure.ECI allows a single digit. Only the right-most digit of the below ECI values is expected in the pullOptions.3DSecure.ECI field.

Possible Values:

1. 02 or 05 - Fully Authenticated Transaction
2. 01 or 06 - Attempted Authentication Transaction
3. 00 or 07 - Non 3-D Secure Transaction

Values per Network:

1. Mastercard - 02, 01, 00
2. VISA - 05, 06, 07
3. AMEX - 05, 06, 07
4. JCB - 05, 06, 07
5. DINERS CLUB - 05, 06, 07
6. Cartes Bancaires (CB) Visa - 05, 06, 07
7. Cartes Bancaires (CB) Mastercard - 02, 01, 00
8. ELO: 05, 06, 07
9. Union Pay International: 05, 06, 07
10. eftpos (Visa or MC) - 05, 06, 07

For more information: https://developers.tabapay.com/reference/3ds-faq

Create Transaction:

3DS APIs only provide a way for you and the issuer to verify a customer's identity. In order to create a transaction you still have to call the create transaction API. The create transaction API has a body param for pullOptions. Within this object, you should find a 3DSecure object. Please look at the 3DSecure object and it's internal fields to know what information you will need to provide the createTransaction API.