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

Integration Options

📘
TabaPay offers 3DSecure authentication as a service
For more information please visit our 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`
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 params.
To find the 3DSecure object, quick find (CTR/CMD + F) 3DSecure or search within the pullOptions object.

Create Transaction Example

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.

Request Body

Create Transaction Examples

{
    "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)

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