How to use the 3DS APIs

Summary

This document gives you a general guide for how to implement 3-D Secure using TabaPay's suite of tools.
*Please 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

TabaPay's 3DS solution has two components. There is a frontend component, and a backend component.

The frontend component depends on the type of client you are using (e.g website, iOS app, Android app). A few things to note:

  1. You can implement your own challenge windows and device data collection. However, you will need to be PCI compliant to do this.
  2. Use the TabaPay SDK for Native mobile apps (coming soon).

The backend component is handled by the TabaPay 3D Secure API. The TabaPay API is a server-to-server API. To connect to it, you need to make sure your backend servers have been whitelisted by the TabaPay team.

Planning for the future:

Please keep in mind that in order to use our 3DS functionality, your team will have to integrate with our backend API and develop either your own frontend solution or integrate with our SDK. These two projects may also work in parallel (we currently do not need them to be integrated in any particular sequence).

Steps in this guide

The following guide is broken down into these steps:

  1. Frontend integration details
    a. Web integration
    b. SDK integration
    c. (non-SDK) Mobile integration

  2. Backend integration details
    a. (optional) Create account
    b. 3DS Initialize
    c. Collect Device Data (through SDK or other methods)
    d. 3DS Lookup
    e. 3DS Authenticate
    f. Create Transaction

🚧

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: https://developers.tabapay.com/reference/device-data-collection

SDK Mobile integration

  • Coming soon with a link to the Guide

(non-SDK) Mobile integration

  • Coming soon with a link to the Guide

📘

(non-SDK) Mobile integration is only an option if you are PCI

In order for your to implement your own native screens from scratch, you will need to be PCI compliant.

Backend integration details

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.

3DS Initialize - Create Initialization/Transactional JWT

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

If you are an ISOISO - Independent Sales Organization, you will need to specify a SubClientID.

URL
https://FQDNFQDN - Replace FQDN with the appropriate domain. Ensure the domain you're using is consistent with the environment you're testing in (sandbox, production, etc.)/v2/clients/ClientIDClientID - Your unique 22-character string issued during onboarding. This value is used in your URLs for TabaPay APIs. For questions on what string to use, ask TabaPay support./3ds/init

Merchant must connect with TabaPay’s 3D Secure Initialize

Notes:
For Clients who are an ISOISO - Independent Sales Organization, 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:

JSON Name

Value

Required

Default

Description

account

object

R

Account

accountID

String
22 characters

R

AccountID

owner

object

O

Owner

phone

object

O

Phone Number (E.164 Numbering)

countryCode

String
1-3 digits

O

1

Country Calling Code

number

String
Min: 4 digits
Max: 12-14 digits

R

Phone Number

order

object

R

Order

orderID

String
1-50 characters

R

Order Number

currency

String
3 digits

O

840

ISO 4217 Currency Number

amount

String
Amount

R

Transaction Amount

Response

Status Codes:

Status

Code

Description

200

OK

A JWT is created.

207

A JWT is created.
207 Multi-Status

Multi-Status One or more Failures occurred while processing the Request.

404

Not Found

The AccountID does not point to a valid Account.

Response Data:

JSON Name

Value

Description

Status Code (200)

Status Code (207)

Status Code (Other)

SC

Integer
3-digit code

HTTP Status Code

O

EC

String
1 or 8 characters

Internal Error Code

O

EM

String

Error Message

O

O

3dsID

String

An identifier representing this Request

jwt

String

JWT (JSON Web Token)

deviceCollectionURL

String
URL

URL for Device Data Collection

Collect Device Data (through SDK or other methods)

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: https://developers.tabapay.com/reference/device-data-collection

🚧

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

3DS Lookup

3D Secure Card Lookup.
If you are an ISOISO - Independent Sales Organization, you will need to specify a SubClientID.

URL
https://FQDNFQDN - Replace FQDN with the appropriate domain. Ensure the domain you're using is consistent with the environment you're testing in (sandbox, production, etc.)/v2/clients/ClientIDClientID - Your unique 22-character string issued during onboarding. This value is used in your URLs for TabaPay APIs. For questions on what string to use, ask TabaPay support./3ds/lookup

Notes:

For Clients who are an ISOISO - Independent Sales Organization, 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

JSON Name

Value

Required

Default

Description

3dsID

String

R

3dsID from 3D Secure Initialize

authenticationIndicator

String
2 digits

R

transactionMode

String
1 character

O

transactionType

String
1 character

R

productCode

String
3 characters

R

account

object

R

Account

accountID

String
22 characters

R

AccountID

owner

object

R

Owner

email

String

R

Email Address

phone

object

O

Phone Number (E.164 Numbering)

countryCode

String
1-3 digits

O

1

Country Calling Code

number

String
Min: 4 digits
Max: 12-14 digits

R

Phone Number

order

Object

R

Order

orderID

String
1-50 characters

R

Order Number

currency

String
3 digits

O

840

ISO 4217 Currency Number

amount

String
Amount

R

Transaction Amount

browser

Object

R

Browser Info

javascriptEnabled

Boolean

O

userAgent

String

O

header

String

O

javaEnabled

Boolean

O

language

String

O

colorDepth

String

O

screenHeight

String

O

screenWidth

String

O

ipAddress

String

O

deviceChannel

String

R

Either:

  • Browser
  • SDK

Response

Status Codes:

Status

Code

Description

200

OK

A Lookup Response is returned.

207

Multi-Status

One or more Failures occurred while processing the Request.

404

Not Found

The AccountID does not point to a valid Account.

Response Data:

JSON Name

Value

Description

Status Code (200)

Status Code (200 Challenge)

Status Code (207)

Status Code (Other)

SC

Integer
3-digit code

HTTP Status Code

O

EC

String
1 or 8 characters

Internal Error Code

O

EM

String

Error Message

O

O

3dsVersion

String

The 3D Secure Version that was used to process this request

enrolled

String

Authentication Eligibility Status

processorTransactionID

String

Processor Transaction Identifier

dsTransactionID

String

Directory Server Transaction Identifier

O

O

status

String

Status

ECI

String

ECI (Electronic Commerce Indicator)

UCAF

String

UCAF (Universal Cardholder Authentication Field)

  • Visa uses CAVV (Cardholder Authentication Verification Value)
  • MasterCard uses AAV (Accountholder Authentication Value)

XID

String

XID (Transaction ID)

O

challengeURL

String

Consumer Authentication URL

payload

String

Encoded Payment Request

Challenge Flow (only when needed)

With the "challenge" payload you get from TabaPay, do this step after receiving a response from the Lookup API and the result is a challenge-flow:

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 (or NetceteraJS) will handle the entire challenge flow from here, and you will receive the authentication result after the challenge completes. The response will contain two fields: data and the jwt. You modify your payments.validated event to handle specific scenarios (specifically look at the data.actionCode)

NOACTION - Authentication was not applicable.

SUCCESS - Authentication was completed successfully.

FAILURE - Authentication resulted in a failure.

ERROR - An error was encountered.

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

3DS Authenticate (only when Challenge Flow is called)

📘

The Authenticate API is called after the challenge is performed.

3D Secure Card Challenge Authentication.
If you are an ISOISO - Independent Sales Organization, you will need to specify a SubClientID.

URL
https://FQDNFQDN - Replace FQDN with the appropriate domain. Ensure the domain you're using is consistent with the environment you're testing in (sandbox, production, etc.)/v2/clients/ClientIDClientID - Your unique 22-character string issued during onboarding. This value is used in your URLs for TabaPay APIs. For questions on what string to use, ask TabaPay support./3ds/authenticate

Notes:
For Clients who are an ISOISO - Independent Sales Organization, 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

JSON Name

Value

Required

Default

Description

3dsID

String

R

3dsID from 3D Secure Initialize

jwt

String

R

JWT (JSON Web Token) from Challenge

Response

Status Codes:

Status

Code

Description

200

OK

A Lookup Response is returned.

Response Data:

JSON Name

Value

Description

Status Code (200)

Status Code (Other)

SC

Integer
3-digit code

HTTP Status Code

O

EC

String
1 or 8 characters

Internal Error Code

O

EM

String

Error Message

O

actionCode

String

Result: Action Code

errorNumber

String

Result: Error Number

errorDescription

String

Result: Error Description

O

3dsVersion

String

The 3D Secure Version that was used to process this request

processorTransactionID

String

Processor Transaction Identifier

status

String

Status

ECI

String

ECI (Electronic Commerce Indicator)

UCAF

String

UCAF (Universal Cardholder Authentication Field)

  • Visa uses CAVV (Cardholder Authentication Verification Value)
  • MasterCard uses AAV (Accountholder Authentication Value)

XID

String

XID (Transaction ID)

O

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.

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.


Did this page help you?