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:
- You can implement your own challenge windows and device data collection. However, you will need to be PCI compliant to do this.
- 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:
-
Frontend integration details
a. Web integration
b. SDK integration
c. (non-SDK) Mobile integration -
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
forpullOptions
. Within this object, you should find a3DSecure
object. Please look at the3DSecure
object and it's internal fields to know what information you will need to provide thecreateTransaction
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 TabaPayToken
through theAccount
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 | R | AccountID | |
owner | object | O | Owner | |
phone | object | O | Phone Number (E.164 Numbering) | |
countryCode | String | O | 1 | Country Calling Code |
number | String | R | Phone Number | |
order | object | R | Order | |
orderID | String | R | Order Number | |
currency | String | O | 840 | ISO 4217 Currency Number |
amount | String | R | Transaction Amount |
Response
Status Codes:
Status | Code | Description |
---|---|---|
200 | OK | A JWT is created. |
207 | A JWT is created. | 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 | HTTP Status Code | ✔ | ✔ | O |
EC | String | 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 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 | R | ||
transactionMode | String | O | ||
transactionType | String | R | ||
productCode | String | R | ||
account | object | R | Account | |
accountID | String | R | AccountID | |
owner | object | R | Owner | |
String | R | Email Address | ||
phone | object | O | Phone Number (E.164 Numbering) | |
countryCode | String | O | 1 | Country Calling Code |
number | String | R | Phone Number | |
order | Object | R | Order | |
orderID | String | R | Order Number | |
currency | String | O | 840 | ISO 4217 Currency Number |
amount | String | 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:
|
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 | HTTP Status Code | ✔ | ✔ | ✔ | O |
EC | String | 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)
| ✔ | |||
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 | HTTP Status Code | ✔ | O |
EC | String | 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)
| ✔ | |
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 theUCAF
,XID
,ECI
which you can use in thepullOptions
of theCreateTransaction
.
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.
Updated 8 days ago