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:

Response

Status Codes:

Response Data:

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

Response

Status Codes:

Response Data:

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

Response

Status Codes:

Response Data:

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.