API Reference
API ReferenceRecipesChangelogCommunity
Start typing to search…

3DS Integration Overview

3DS is a powerful fraud protection tool that provides a merchant with the ability to authenticate if a person is allowed to use a card. In certain cases, authentication also provides a shift in liability for certain types of chargebacks. TabaPay offers 3DS via our 3DS partner Cardinal Commerce.

Technical integration

3DS integration can be broken up into two portions:

  1. Frontend integration -> Integrating with the Cardinal Commerce 3DS SDKs.
  2. Backend integration -> Integrating with the TabaPay 3DS APIs.

Frontend integration

The frontend integration can be further divided into two versions depending on what kind of devices you support.

  1. Mobile SDK integration (iOS and Android SDKs)
    1. If your application is on an App Store, then you are probably going to need to integrate using the mobile SDKs.
  2. Browser flow integration (Songbird.js)
    1. If your application is accessed via a browser (Firefox, Chrome, Safari, etc.), then the browser integration might be for you!

📘

What's a browser?

Browser:

"A Browser is a dedicated software application for accessing information on the World Wide Web, for example Chrome, Safari, Edge, Firefox. When a user requests a web page from a particular website, the Browser retrieves the necessary content from a web server and then displays the page on the consumer’s screen. In the context of 3-D Secure, the Browser is a conduit to transport messages between the Acquirer Domain and the Issuer Domain. A Browser is distinguished from a UI component for example, a WebView, or Custom Tabs, which can be used to display content within an App on a mobile device. The Browser flow is invoked by a Browser whereas the EMVCo specification does not support a UI component within an app invoking the Browser flow."

-EMV® 3-D Secure Protocol and Core Functions Specification v2.3.1.0

Backend integration

There are three primary APIs for 3DS authentication. You will need to integrate with all three APIs in order to complete your 3DS integration.

  1. 3D Secure Initialize
    1. Used at the start of every 3DS authentication.
  2. 3D Secure Lookup
    1. Use every time you wish to perform a 3DS authentication.
  3. 3D Secure Authenticate
    1. Used only after a challenged authentication to validate the result of a challenge.

Additional technical integrations

The 3DS APIs only perform customer authentication, you will need a few additional APIs and tools to complete your flow:

  1. Transmitting Card data - if you are not PCI compliant, you can use the TabaPay PCI helpers:
    1. PCI Helper - RSA for mobile applications
    2. PCI-Compliant iFrame for websites
  2. Card storing and passing card info the the 3DS APIs - you can store card data with TabaPay using our TabaPay Tokens. Once you store the card data, you will be able to use these TabaPay Tokens to call the 3DS APIs.
    1. Create Account - To store card data, you will need the resulting accountID to send card data to the 3DS APIs and the Create Transaction API.
  3. Authorization Request - 3DS is purely an authentication tool. It does not, on its own perform any authorizations. It is up to the merchant to analyze the results of the authentication, and perform any additional fraud prevention checks/analysis before moving forward with authorization. Once the merchant is confident of the transaction, and ready to request that funds be moved, then they must use the Create Transaction API.
    1. To attach the results of the authentication to a transaction, you will need to use the pullOptions.3DSecure object.
    {
    "referenceID": "MYuniqueID",
    "type": "pull",
    "accounts": {
        "sourceAccountID": "BikavmIjUhYgTfdMwv5g3A",
        "destinationAccountID": "UgvbOGRaGNfUaHU9Lulwsq"
    },
    "amount": "50.00",
    "pullOptions": {
        "3DSecure": {
        	  "version": "2",
            "ECI": "5",
            "UCAF": "2",
        }
    }
}

Implementation Guides:

TabaPay offers two implementation guides:

  1. 3DS Browser flow implementation: Includes information about both the frontend and backend integrations.
  2. 3DS Mobile SDK implementation: Includes information about both the frontend and backend integrations.

Important information - Required info

🚧

Please read the following information about required data before beginning your integration.

3DS authenticates whether a person is allowed to use a card. As such, 3DS needs the following information about the cardholder as part of its authentication process.

  1. Card number [Required]
  2. Expiration date [Required]
  3. Address [Required]
    1. Line 1 - Required unless market or regional mandate restricts sending this information.
    2. Line 2 - Conditional - Required if information is available, unless market or regional mandate restricts sending this information.
    3. City - Required unless market or regional mandate restricts sending this information.
    4. State - Required - Required if information is applicable and BillingCountryCode is present, unless market or regional mandate restricts sending this information.
    5. Country code - Required unless market or regional mandate restricts sending this information.
  4. Phone [Required]
  5. First name [Required] - Has to be added to the AccountID. Has to be Personal Name, NOT Company Name (e.g. "Stacy", "Neal").
  6. Last name [Required] - Has to be added to the AccountID. Has to be Personal Name, NOT Company Name (e.g. "Wayne", "Wang").
  7. Email address [Required] - This is provided in the 3D Secure Lookup call.

Additional required data for create transaction with 3DS

📘

This is not exhaustive

There may be additional data that is not listed below that is required for a 3DS transaction. This is just a subset we would like to highlight.

3DS Liability Shift Criteria

  1. Address [Required]
  2. Line 1 - Required unless market or regional mandate restricts sending this information.
  3. Line 2 - Conditional - Required if information is available, unless market or regional mandate restricts sending this information.
  4. City - Required unless market or regional mandate restricts sending this information.
  5. State - Conditional - Required if information is applicable and BillingCountryCode is present, unless market or regional mandate restricts sending this information.
  6. Country code - Required unless market or regional mandate restricts sending this information.

In addition to the pull options:

....   
"pullOptions": {
        "3DSecure": {
        	  "version": "2",
            "ECI": "5",
            "UCAF": "2",
        }
    }
....

Body Parameter

Type

Description

3DSecure

Object

Contains 3DS related fields

Version

String

Version of 3DS (e.g. 2)

ECI

String

Electronic Commerce Indicator (ECI) values Visa 5, 6, or 7 MasterCard 2, 1, or 0 Amex 5, 6, or 7 Others 5, 6, or 7

UCAF

String

Universal Cardholder Authentication Field (UCAF) values 0 Missing UCAF 1 Invalid UCAF 2 Invalid Security Level Indicator (SLI). If you receive this code, please let TabaPay know via [email protected]

XID

String

Transaction ID for Amex. Otherwise, optional

dsTransactionID

String

Directory Server TransactionID

Required if card network is MasterCard. Otherwise, optional

📘

Associating Cardholder Address for Authorizations with 3DS

If clients create a TabaPay Token with the cardholder address, and they perform a Create Transaction API with that TabaPay Token + 3DS payload, TabaPay will use the cardholder address associated with the TabaPay Token

(1) If the address has changed, clients can update the account with that new address, and perform (1) OR they can do (3)
(2) If the address has changed, clients can create a new account with the new address, and perform Create Transaction API with that TabaPay Token + 3DS payload, TabaPay will use the new cardholder address associated with this newly created TabaPay Token (3) If the address has changed, clients can use the CreateTransaction API without an accountID. Instead, they would need to collect the PAN (via our PCI tools, etc.) and send in the new address + the 3DS payload.

Let's say a client DOES NOT include address at the time of TabaPay Token creation AND if the client wants to perform a Create Transaction API request WITH an address, these are their choices:

Payment Instrument association with Address

  1. Update TabaPay Token using Update Account API with a new address to the existing token. Perform Create Txn API with this TabaPay token.
  2. Create a new TabaPay Token using the PAN and the address. Perform Create Txn API with this TabaPay token.
  3. Perform Create Txn API with PAN and address.

NOTE: Create Txn API with a TabaPay Token and a new address does not work.

Create Transaction API with 3DS

For 3DS clients, Create Txn API options, to avoid 10.4 are:

  1. PAN + Address + 3DS Payload
  2. TabaPay Token + 3DS Payload

Recommendations

  1. In the 3DS APIs OrderID is a unique identifier generated by the merchant. We recommend using the same value as your CreateTransaction ReferenceID. This is not required, but it makes it easier for the support team to find the lookup request associated with your transaction.

Additional information

📘

For more information:

3DS FAQs: https://developers.tabapay.com/reference/3ds-faq