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:

1. Authentication - Authenticate 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. However, merchants can also integrate directly with their own 3DS service provider. The only thing to note is this: you are going to need the ability to send card data to both TabaPay and to the 3DS provider securely. If you are using TabaPay's PCI helpers, then you will have to use TabaPay's 3DS Solution.
2. Authorization - When you actually move money. Regardless of which 3DS service provider your choose, you can attach the results of a successful, payment authentication to your transactions.

📘

When to perform a transaction?

3DS provides information to the merchant that can be used to decide whether or not to move forward with a transaction. For example, 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:

These fields can be found on our documentation for Create Transaction. Simply look for the field pullOptions, and within it you will find the 3DSecure object.

Example transaction body parameters:

📘

Additional data

Please note that 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. The sample below is just an example, but it does not represent all possible combinations. Please focus your attention on the pullOptions block at the bottom of the example.

body: {
    "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":{
      	"ECI":"5",
        "UCAF":"long string"
      }
    }
  }

A few things to note:

1. You can provide the resulting CAVV in the UCAF request field.
2. The Create Transaction API only needs the second digit in the ECI field:
   1. 05 => 5
   2. 00 => 0
3. 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
4. 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