The following guide describes how to use create a transaction using the 3D Secure (3DS) values you received from your 3DS service provider (TabaPay or otherwise).

Integration Options

TabaPay offers 3DS authentication as a service. To get started with 3DS, refer to 3DS Integration Overview.

3DS is a fraud prevention tool that provides a merchant with the ability to introduce an additional layer of authentication as part of the payment process. In certain cases, authentication also provides a shift in liability for certain types of chargebacks. TabaPay offers 3DS via our 3DS partner Cardinal Commerce.

3DS integrations involve two different services:

Authentication is performed via a 3DS provider. This is when you send an issuer a message ("3D Secure Lookup", "AReq", etc.) asking them to verify if the person performing the transaction is allowed to do so. TabaPay offers 3DS as a service via our 3DS partner Cardinal Commerce.

If you use your own 3DS provider you will need the ability to send card data to both TabaPay and to the 3DS provider securely.
If you are using TabaPay's Basic Custom iFrame, then you will have to use TabaPay's 3DS Solution.

When should we perform a 3DS transaction?

3DS should be used in situations where additional confidence in cardholder identity is needed.

3DS provides both authentication signals and risk data that can help you decide whether to proceed with a transaction. For example:

If authentication fails or returns weak signals, you may choose to challenge, step-up, or decline based on your fraud strategy.
If a merchant sees one or more failed authentications, they might want to be cautious of potential fraud.

Create 3DSecure Transaction - Authorization Message

Once you have completed the necessary 3DS steps (3DS Integration Overview), depending on the final result of the authentication, you will receive the following fields:

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` Note:
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

These fields can be found on our documentation for Create Transaction API.

Go to Create Transaction API.
Select the Expand All button at the top of the body parameters.
To find the 3DSecure object, quick find (CTR/CMD + F) 3DSecure or search within the pullOptions object.

Create Transaction

The example does not represent all possible combinations. Notice the 3DSeucre object within the pullOptions object.

You may or may not need additional data (e.g. address, name, XID, dsTransactionID) depending on your use case, purpose of the transaction, network, etc.

Create Transaction Request Body

The 3DS Authenticate API returns values in a different format than Create Transaction requires. Reformat the following before submitting:

ECI — strip the leading zero. 05 → 5
version — use the first digit (integer only). 2.2.0 → 2

{
    "referenceID": "MYuniqueID",
    "type": "pull",
    "accounts": {
        "sourceAccountID": "BikavmIjUhYgTfdMwv5g3A",
        "destinationAccountID": "*redacted*"
    },
    "amount": "10.00",
    "pullOptions": {
        "3DSecure": {    <----- 3DSecure Object,
            "version": "2",
            "ECI": "1",
            "UCAF": "2"
        }
    }
}

{
    "referenceID": "MYuniqueID",
    "type": "pull",
    "accounts": {
      "sourceAccount": {
        "card": {
          "keyID":"[keyID]",
          "data":"[data]"
        },
        "owner": {
          "name": {
            "first": "Jane",
            "last": "Doe"
          },
          "address": {
            "line1": "A street",
            "city": "Mountain View",
            "state": "CA",
            "zipcode": "94043",
            "country": "840"
          },
          "phone": {
            "countryCode": "1",
            "number": "55541112222"
          }
        }
      },
      "destinationAccountID": "*redacted*"
    },
    "amount": "10.00",
  	"pullOptions":{
    	"3DSecure":{   <----- 3DSecure Object,
      	"ECI":"5",
        "UCAF":"long string"
      }
    }
  }

You can provide the resulting CAVV in the UCAF request field.
The Create Transaction API only needs the second digit in the ECI field:
1. 05 => 5
2. 00 => 0
The Create Transaction API only needs the first digit in the version field:
1. 2.1.0 => 2
2. 2.2.0 => 2
3. 1.2.1 => 1
Best practice might be "if we offer a 3DS field in the pullOptions and you received a value for it from your 3DS service provider, please send that info (i.e. dsTransactionID, XID, version)

Combining Create 3DS Transaction with other Features

3DS adds an additional layer of authentication as part of the payment process. You may want to combine 3DS with other features like Apple Pay, Google Pay, Partial Auth, Auth & Capture and other Card Holder Initiated Transactions (CIT)s.

However, there are some features that may not work with 3DS such as Merchant Initiated Transactions (MIT), due to the cardholder's absence in the transaction process for MITs.

🚧
3DS version 1 has been sunset as of Oct 2022