Best Practices
Our APIs are agnostic of each other
Please note that all of our APIs are agnostic of each other. If you call the 3DS APIs, but do not pass the proper values in the
CreateTransactionAPI then the transaction will not be protected by 3DS.
Be consistent when using the APIs
The TabaPay APIs provide a lot of flexibility and control for you. However, it is important to be consistent when using our APIs.
When calling the 3DS APIs, make sure you use the same card for all of the API calls and for the Create Transaction call at then end of the process.
If you decide to use an Account ID for 3DS, but then call the Create Transaction API using our PCI helpers, there is a chance that the underlying card number may not match leading to issues.
What are the potential timeouts?
-
How long does the JWT last before it times out?
2 hours by default. Could be shorter if you include an exp claim. -
How long does a person have to respond to a challenge before it times out?
10 minutes -
Once we have a successful authentication (ECI, CAVV, etc.) how long do we have before these values expire? Can we run a 3DS authentication today, store the value, and use it a week from now? A day from now? 8 hours from now? etc.
The CAVV would be valid for up to 90 days. -
Are there any other timeouts you need to keep in mind?
Once the lookup response is received with a challenge URL and payload you will have 30 seconds to facilitate the challenge session before it expires.
What's a browser?
Browser:
"A Browser is a dedicated software application for accessing information on the World Wide Web, for example Chrome, Safari, Edge, Firefox. When a user requests a web page from a particular website, the Browser retrieves the necessary content from a web server and then displays the page on the consumer’s screen. In the context of 3-D Secure, the Browser is a conduit to transport messages between the Acquirer Domain and the Issuer Domain. A Browser is distinguished from a UI component for example, a WebView, or Custom Tabs, which can be used to display content within an App on a mobile device. The Browser flow is invoked by a Browser whereas the EMVCo specification does not support a UI component within an app invoking the Browser flow."
-EMV® 3-D Secure Protocol and Core Functions Specification v2.3.1.0
Help me through things I need to consider when I think of 3DS.
TabaPay Clients should:
- Create an EMV 3DS strategy prior to implementation that includes defining the objectives and key performance indicators (KPIs) upfront to drive implementation.
- Examples of objectives include combatting fraud or gaining compliance to local or regional regulations.
- Examples of KPIs include a lift in sales or increase in authorization rates.
- Define the primary objectives for implementation upfront to drive the crucial solution design.
- Inventory all checkout flows and purchase journeys available to your consumers to understand the various checkout experiences so the implementation of EMV 3DS can be optimized across each one.
- Work with their acquirers to ensure proper monitoring is in place. Acquirers may provide Issuer reported fraud data that can give insight to important KPIs (fraud to sales rations or approval rates on EMV 3DS vs non-3DS transactions
- Submit lookup requests with as much additional data as possible, which will provide Issuers with more data to improve their risk models and risk assessment, and lead to more frictionless authentications. Use EMV 3DS for:
- Authenticating the cardholder for guest checkout transactions as consumer is not known to the Merchant
- First time use or subsequent higher value and/or out of pattern purchase transaction
- Suspected account take over scenarios (i.e., address change, user id /password updates)
•~~ Continually monitor their check-out process and work with their 3DS Server provider to make adjustments as needed to improve checkout experience.
• Implement monitoring on Fraud-to-Sales Ratio, and Approval rates on 3DS vs. non 3DS transactions and make adjustments to risk strategies and implementation approaches accordingly~~
What data must I provide with every 3DS transaction?
TabaPay Clients should ensure that the data sent into authorization is accurate and consistent with the data sent into authentication.
The more, accurate/high quality data clients can provide for 3DS, the better. The more
information Issuers have to feed their risk engines will be a driver in frictionless/challenge outcomes so any TabaPay Client interested in driving down challenge rates should be looking to supply as much data as they can.
Per EMV® 3-D Secure Protocol and Core Functions Specification v2.3.1.0 (August 2022) and Cardinal API Requirements
| 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 | ||||
| String | R | Email Address | |||||
| phone | object | R - Required (if available) unless market or regional mandate restricts sending this information. | 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 | ||||
| address | object | R - Required unless market or regional mandate restricts sending this information. | If you are using an `AccountID` you would add the address to the account using `CreateAccount`. | ||||
| line1 | String | R -
Required unless market or regional mandate restricts sending this information. |
Address Line 1
If you are using an `AccountID` you would add the address to the account using `CreateAccount`.
|
||||
| line2 | String | Conditional -
Required if information is available, unless market or regional mandate restricts sending this information. |
Address Line 2
If you are using an `AccountID` you would add the address to the account using `CreateAccount`.
|
||||
| city | String | R -
Required unless market or regional mandate restricts sending this information. |
City
If you are using an `AccountID` you would add the address to the account using `CreateAccount`.
|
||||
| state | String | Conditional -
Required if information is applicable and BillingCountryCode is present, unless market or regional mandate restricts sending this information. |
State
If you are using an `AccountID` you would add the address to the account using `CreateAccount`.
State Code must be a valid 2-character code if country is `840` or `124`.
|
||||
| zipcode | String | R -
Required unless market or regional mandate restricts sending this information. |
Zip Code
If you are using an `AccountID` you would add the address to the account using `CreateAccount`.
|
||||
| Country Code | String | R -
Required unless market or regional mandate restricts sending this information. |
Country Code (e.g. 840)
If you are using an `AccountID` you would add the address to the account using `CreateAccount`.
|
||||
| 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 Data. Issuers fallback to data provided here if Device Data Collection fails. | ||||
| browserInfo | String | O | Concatenated Browser Data Fields. See this page for the exact format. |
||||
| 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:
|
||||
Additional information
In the 3DS APIs OrderID is a unique identifier generated by the merchant. We recommend using the same value as your CreateTransaction ReferenceID. This is not required, but it makes it easier for the support team to find the lookup request associated with your transaction.
How should I think of consistency?
TabaPay Clients should be aware that there are two types of data:
- Systemic data (i.e. transaction amount, IP address and device) that is captured systemically
- Manually entered data that are customer input fields
- Customer input fields have been found to result in a higher rate of error at approximately 3%. When possible, implementing a drop-down menu of required fields for consumers to select their information, and ensuring card-on-file is present can greatly reduce the rate of human error.
- For addresses, not every country has the same address conventions (i.e. provinces, states, territories). Whenever possible, Merchants should use a dropdown feature to improve accuracy and reduce human error in manually entered data.
- As a best practice, Merchants should allow card-on-file and consumer pre-filled data to ensure consistent entries for returning customers. This also improves consumer experience.
Merchant Dispute Protection
What are guidelines for disputes for 3DS transactions?
| Restriction | ECI | Description |
|---|---|---|
| CAVV Not Present | ECI 05 or 06 for Visa; ECI 02 or 01 for MasterCard | Merchants are not protected when CAVV is not present |
| Non-Reloadable Prepaid | ECI 06 or ECI 02 | Merchants are not protected when card type is a non-reloadable Visa prepaid card. |
| Network Fraud Monitoring Program | ECI 05 or 06 for Visa; ECI 02 or 01 for MasterCard | Merchants are not protected if they have been identified in the program. Merchant/acquirers in the program should submit transactions using ECI 07 with no CAVV. |
| Custom Payment System (CPS) Requirements | ECI 05 or 06 for Visa; ECI 02 or 01 for MasterCard | Merchants are not protected if transaction does not meet CPS requirements. |
| Merchant Restricted Merchant Category Codes (MCCs) | ECI 05 or 06 for Visa; ECI 02 or 01 for MasterCard | Merchants are not protected if they are in one of the following MCCs: • MCC 4829—Wire Transfer/Money Order • MCC 6051—Non-Financial Institution- Foreign Currency, Money Order (not Wire Transfer), Travelers’ Cheques • MCC 7995—Betting, including Lottery Tickets, Casino Gaming Chips, Off-Track Betting and Wagers at Race Tracks • MCC 6540 - Non-Financial Institutions: Stored Value Card Purchase / Load • MCC 7801 - Government Licensed On-Line Casinos (On-Line Gambling) |
Liability Shift
Does 01 or 06 guarantee liability shift?
There is no guarantee on liability shift, and TabaPay does not control liability shift. However, performing 3DS assures cardholder authentication by the Issuing bank.
How do I know liability shift is guaranteed?
TabaPay will soon be adding CAVV Results Code in the Create Transaction API Response. This field would provide insights into liability shift for 3DS transactions (i.e. transactions processed with a 3DS payload) See CAVV Results Code here: https://developers.tabapay.com/reference/cavv-results-code
3DS Decisioning
What does TabaPay recommend clients do at the end of 3DS and if the transaction must be processed?
We recommend looking at the following Cardinal Documentation for more information -> Consumer Authentication Matrix.
Some additional observations:
- 02 or 05 - Fully Authenticated Transaction -- TabaPay recommends going ahead with the transaction
- 01 or 06 - Attempted Authentication Transaction -- TabaPay recommends going ahead with the transaction, and monitor activity. If post-processing, it results in any untoward activity, you can tweak this logic.
- 00 or 07 - Non 3-D Secure Transaction -- TabaPay does not recommend going ahead with the transaction
How should we treat Enrolled = U or N?
If the Enrolled equals U or N, it is good to [assume] that the issuer does not participate and you should "not" proceed with "Authorization" because if you do, then you would be held liable, since authentication was not accepted. You can proceed with "Authorization" as that is entirely up to the merchant and how they conduct their business. These are rules that you can use on your Payment Gateway, which is separate from CardinalCommerce Authentication.
If enrollment does equal "Y", then it is best to proceed via a Frictionless Transaction or a Challenge on Authentication and from there if Authentication passes with Status Y, then proceed. If it fails, with a N or a U, then you should not proceed but again, you may do so, but liabality will be on the merchant, not the issuer.
Exceptions
What do I do when a 3DS transaction aborts for some reason?
When there's an error, without a CAVV at the end of 3DS, you can only proceed with ECI 07 (no CAVV) for the transaction. Or re-try.
However, if during a 3DS flow, the issuer is unavailable, the result would usually result in ECI 06 and a CAVV with issuer not present indication. You can proceed with ECI 06 and CAVV for processing.
Additional questions:
- Can we rely on the vendor to address any issues that may arise during AND AFTER integration?
Specific issues related to the SDK and its functionality, yes. Prior to going live, we recommend the merchant completes all testing/test cases, building logic to handle responses and errors. Once the merchant moves to production, if there are any issues TabaPay would reach out to Cardinal’s support team via a support ticket with the issue and it would be handled on a case-by-case basis. - How would we communicate issues to the vendor?
The merchant would raise the issue with Tabapay which would then open up a support ticket with Cardinal. - What is the vendor’s SLA for addressing issues?
This would depend on the issue at hand. For example, if it was a bug fix needed within the SDK, those would come about/be addressed in any upcoming sprints at Cardinal (again, based on the severity or complexity of the issue). When TabaPay opens a support ticket, the SLA's would follow our Cardinal’s SLA procedures. - Does Vendor SDK support all platforms/OS versions currently supported by Client App?
The Cardinal Mobile SDK for iOS requires iOS 10 (at the minimum) and is compatible with any version later than that. The Cardinal Mobile SDK for Android requires an API level of 21 (Android 5.0, Lollipop, or later) and is compatible with any version later than that. - Can we rely on Vendor to support all future versions of platforms/OS versions?
Yes, Cardinal will continue to support all future platforms/OS versions for iOS and Android. - Can Cardinal also support sending 2FA code via phone call, in addition to SMS?
Answer: It depends on the Issuing bank, the cardholder would need to work with their Issuing Bank to setup their 2 Factor authentication preferences. - Is 2FA via email a hard requirement, or an option?
Answer: This is an option. Most user's prefer a text message. - Can you provide more details on error flows, if any (what they look like, and in what scenarios are they triggered)?
Answer: For 3DS test cards look at the following: https://developers.tabapay.com/reference/3ds-test-cases-and-cards
There are numerous scenarios for errors. We don't have specific error flows, but a common scenario would be 1.0 downgrades (in the case of a 1.0 downgrade, TabaPay will return a 207 response code. Please contact [email protected] if you receive any 207 response codes and DO NOT retry). - Is there a built-in success screen, or would the client build that?
Answer: The Issuing bank actually has the private session with their cardholder and would be controlling the challenge screen if a cardholder is successful or not. - Is there a max number of retries? Is that configurable on the client side?
Answer: 3 attempts. If the transaction fails after 3 attempts of incorrect password being input, the cardholder would then need to re-initiate the transaction.