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

πŸ“˜

Make sure you have 3DS on your TabaPay Plan.

3DS 2.0 requires cardholder address as part of the authentication process at the issuer. This means, TabaPay's 3DS API/SDK will fail if the payment instrument does not have a corresponding address. If you're using Account ID as the payment instrument for 3DS, it must have billing address associated with it. So, please ensure you create accounts by providing address always

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 ISO, you will need to specify a SubClientID.

URL
https://FQDN/v2/clients/ClientID/3ds/init

Merchant must connect with TabaPay’s 3D Secure Initialize

Notes:
For Clients who are an ISO, 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. In summary, Device Data Collection has three possible methods depending on your implementation:

  1. If you are implementing 3DS using a browser or webview you could use:
    1. Songbird.js a Javascript library for 3DS.
    2. Implement 3DS without Songbird.js
  2. If you are implementing 3DS in a native app, you can use our 3DS SDK.

🚧

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 ISO, you will need to specify a SubClientID.

URL
https://FQDN/v2/clients/ClientID/3ds/lookup

Notes:

For Clients who are an ISO, 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.

Lookup codes

The following documentation has the values you should use for the lookup call:

  1. Authentication Indicator
  2. Transaction Mode
  3. Transaction Type
  4. Product Code

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:

StatusCodeDescription
200OKA Lookup Response is returned.
207Multi-StatusOne or more Failures occurred while processing the Request.
404Not FoundThe 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

Examples of what your customers might see: https://developer.visa.com/pages/visa-3d-secure/payment-flows-otp

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 ISO, you will need to specify a SubClientID.

URL
https://FQDN/v2/clients/ClientID/3ds/authenticate

Notes:
For Clients who are an ISO, 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 NameValueRequiredDefaultDescription
3dsIDStringR3dsID from 3D Secure Initialize
jwtStringRJWT (JSON Web Token) from Challenge

Response

Status Codes:

StatusCodeDescription
200OKA 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.