3D Secure

Overview

This page offers a complete collection of guides and tutorials about 3D Secure in the PayConex® API. It includes an introduction to the 3D Secure protocol, detailed explanations of its benefits, and step-by-step instructions on how to configure and use it effectively within the PayConex® system. Whether you're new to 3D Secure or looking for advanced implementation details, this resource has everything you need to get started.

As 3DS falls into the category of Fraud Prevention, we recommend reading up on:

• Fraud Prevention
• Fraud Scoring

3DS Protocol

3D Secure (3DS) is a protocol that adds a layer of security to prevent fraud in eCommerce transactions with credit & debit cards. It sits on the merchant's payment form and authenticates customers in real-time during card not present transactions.

📘

FAQ: Can 3D Secure help in lowering interchange rates?

3-D Secure qualifies transactions as "less risky" on a network level - enabling Visa and Mastercard to offer lower interchange rates on reward cards.

"3D" refers to the "three domains" involved in the protocol's interaction:

• Interoperability domain: The payment system or gateway between the other domains
• Merchant/acquirer domain: The environment for the merchant’s or acquirer's processing
• Issuer domain: The cardholder's bank or issuer's environment

Here is an illustration of the relationship of these three domains combined.

For more information on the 3DS Protocol in more depth, refer to EMV® 3-D Secure.

3D Secure Workflow

The complete 3D Secure workflow is divided into two main iterations:

1. 3DS Authentication with the issuing bank driven by a 3DS service

2. Authorization of payment with 3DS data

3D Secure sits on the merchant's payment form and allows the acquiring bank to verify the cardholder's identity with the issuing bank. The authentication happens within milliseconds behind the scenes and starts as soon as the cardholder finishes typing their information. The authentication is completed without further shopper interaction. All of this occurs in the browser environment.

📘

FAQ: When does the authentication Happen?

The authentication starts as soon as the customer finishes entering their credit card information on the merchant payment form prior to the customer hitting submit. If the transaction is authenticated the merchant will receive 3DS data that is then passed to the gateway and finally to the processor. There is no impact on the customer experience, everything happens on the back-end. After you enter your credit card information, you will see the authentication happen. Note that your credit card won't be charged as this can be done in the certification environment. For more on that, see 3D Secure Merchant Plug-In.

This workflow can be depicted in the following diagram:

1. 3D Secure Service: After successful authentication with the card network and the issuing bank, the 3DS data results are appended to the payment request.

2. Authorization of payment: If the issuing bank approves authorization, the transaction proceeds to settlement with the payment processor and acquiring bank (back-end processing).

   • If authentication has previously failed, the 3DS data is stripped from the meta-data, and the transaction is not considered 3DS-Authenticated. The handling of transactions with failed 3DS data—whether they are blocked or processed—depends on the business rules and configuration of the payment gateway or acquirer, varying based on the strictness of a system setup. As a secondary line of defense when 3DS fails, Anti Fraud Scoring is also typically used.

📘

FAQ: Who is Bluefin’s 3D Secure service?

Bluefin utilizes its proprietary TECS 3DS Solution, designed in compliance with the EMV® 3-D Secure Protocol and Core Functions Specification certified for Visa, Mastercard, Discover and AMEX. This solution is fully integrated into the PayConex® System, ensuring that all PayConex® users are automatically supported with 3D Secure functionality. It ensures a smooth user experience while maintaining high security standards.

Bluefin TECS 3DS can be simulated via 3DS MPI in the certification environment for testing purposes.

Bluefin TECS 3DS Workflow

As outlined in the 3D Secure Workflow, the Bluefin TECS 3DS service manages the 3DS authentication. This is summarized in the following key points.

• Browser-to-3D Secure Communication: Forms the real-time link that verifies the cardholder.

• Data Generation: The Bluefin TECS 3DS service creates and returns ddds_* parameters for the subsequent transaction.

• Universal Application: This applies to the iFrame, Hosted Payment Forms, and API-based approach - especially for large ISVs with their own PCI-compliant environments.

• ISV Use Case: Large ISVs with their own PCI-compliant environment can integrate directly with Bluefin TECS 3DS and the API-based approach.

📘

Note

This workflow can be simulated via 3DS MPI in the certification environment for testing purposes.

1. Challenge Initiation: Once the customer fills out the initial form (with 3DS enabled), Bluefin TECS 3DS sends a request to the issuing bank to initiate a challenge. At this point, the communication bridge between the issuing bank and the browser is established.
2. Challenge Completion: Based on the chosen challenge indicator, a challenge is presented to the customer for completion.
3. 3DS Data: After the challenge is successfully completed, the PayConex® API returns all of the ddds_* data parameters necessary for a subsequent transaction request such as a sale, authorization, store, etc. These are then reused to either compose eToken via the iFrame encrypt function or are provided directly in a transaction API request.

📘

FAQ: What data elements are passed to authenticate a cardholder?

For 3DS authentication, the following data elements are passed to the issuing bank’s Access Control Server (ACS): 16-digit card number, expiration date, CVV, browser URL or app URL, IP address, and device fingerprinting data.

Access Control Server (ACS) refers to the issuing bank’s software that authenticates e-commerce transactions through the 3D Secure network.

3D Secure Merchant Plug-In

Our Bluefin TECS 3D Secure Merchant Plug-In (MPI) is used in both testing and production environments, but its purpose and setup may vary:

1. Testing Environment:
   • In the testing or certification phase, the MPI typically interacts with test systems, such as a simulator for the Access Control Server (ACS). This allows merchants and developers to validate their integration without involving real-world transactions. Test cards and mock responses are used to simulate various scenarios, including successful authentication, challenge flows, and errors.
2. Production Environment:
   • In production, the MPI handles live transactions, interacting with the actual ACS and directory servers of card networks (e.g., Visa, Mastercard). Its role here is to facilitate cardholder authentication and ensure compliance with 3DS protocols for secure payment processing.

📘

Did you know?

This 3DS solution is also integrated in the Bluefin TECS Web for all kinds of transactions including MITs, CITs, and COF transactions. To compare the PayConex® system and TECS Web integrations, check out TECS 3D Secure Transaction.

Chargeback Reason Codes

In the back-end, authenticated transactions receive a chargeback liability shift and go straight to the issuer. Here is a brief table of fraud chargeback codes. As there are various types of chargeback reason codes, check out the following comprehensive documents:

• Mastercard
  • Chargeback Guide Merchant Edition
• Visa
  • Chargeback Management Guidelines for Visa Merchants
  • Dispute Management Guidelines for Visa Merchants

📘

FAQ: Does 3D Secure completely prevent chargebacks?

The answer is both "yes" and "no" because it depends on the chargeback reason code.
3D Secure can reduce certain fraud chargebacks and "friendly fraud" such as:

• 4837 - No Cardholder Authorization
• 4849 - Questionable Merchant Activity
• 4863 - Cardholder Does Not Recognize - Potential Fraud

For more reason codes, check out Chargeback Reason Codes.

3D Secure alone will not eliminate all chargebacks.

📘

FAQ: What is "friendly fraud"?

"Friendly fraud" refers to a legitimate purchase made by a consumer with their credit card which is later disputed with the issuing bank rather than requesting an exchange or refund from the merchant. It can be malicious, but more often, there is a misunderstanding. Friendly fraud can account for 40% - 80% of all fraud losses.

Mastercard Fraud Chargeback Reason Codes

Visa Fraud Chargeback Reason Codes

Requirements

The user must enable the 3D Secure option in the PayConex® Portal settings, under the Security Features section, using our Bluefin TECS 3DS solution as the 3DS service. In the PayConex® Portal, this service is labeled and referred to as BLUEFIN, as shown in the example below.

🚧

Note

The Bluefin Administrators must first enable this security feature for all three implementation options to support 3DS. If you do not see it in the Settings, please reach out to the Bluefin Technical Team for assistance.

Anti-Fraud Scoring is also enabled by the Bluefin Administrators. For the complete guide, check out Fraud Scoring.

3DS Data Parameters

The 3DS data parameters, prefixed with ddds_*, are required in the transaction request for a successful 3DS transaction. The second 3DS iteration for the payment request adds these parameters as transaction meta-data.

Common Visa 3DS Status Codes

For more information, the Merchant/Acquirer Implementation Quick Reference for 3-D Secure 2.0 offers guidance tailored for merchants and acquirers.

3D Secure Implementation Options

The authenticated 3D Secure data can be provided in a QSAPI transaction in the following three ways:

• iFrame: Using the eToken generated and encrypted via the iFrame Component with the built-in Bluefin PCI-compliant environment in place. This token encrypts and includes all of the ddds_* data parameters and the sensitive credit/pan data.
• Hosted Payment Forms: Enabling 3D Secure for Hosted Payment Forms incorporates the 3D Secure feature per form. The form applies the 3DS data to a QSAPI transaction and processes it. Compared to the encrypted iFrame eToken, after the Bluefin TECS 3DS workflow is completed, the form uses the raw card data and the 3DS data directly in a QSAPI transaction. This variant is also PCI-compliant.
• API-based: This approach uses the raw credit/pan data and manually includes the 3D Secure data returned from the endpoints via Bluefin TECS 3DS Solution. However, apart from Hosted Payment Forms, we recommend this approach only for large ISVs with their own PCI-compliant environment. For this implementation variant, please contact the Bluefin Technical Support first.

For more detailed instructions, select how you want to integrate:

iFrame

🚧

Note

Before configuring 3D Secure settings for iFrame, make sure to satisfy the Requirements first.

Before reading this implementation option, consider reading over iFrame.

3D Secure on iFrame (Configuration & Set up)

3D Secure settings can be configured from the PayConex® Account Settings page under the iFrame options.

📘

Note

If you have trouble with setting up the Domain Whitelist, refer to iFrame Implementation.

eToken Enabled

The dropdown selections include:

3DS Challenge Indicator

3DS Challenge Display Option

3D Secure & the iFrame SDK

To support 3D Secure, the encrypt function on the Payment iframe can consume a 3D Secure data object containing transaction meta-data. However, this data is not stored in the PayConex® system and is exclusively used for 3DS Authentication. If a merchant wishes to provide it as transaction meta-data, the same customer-information fields can be included in a QSAPI transaction request.

While the object has over 20 fields, the minimum fields required for most card brands are amount and cardHolderName. However, Amex requires the additional fields shipIndicator, deliveryTimeFrame, and reorderItemsInd.

These fields are the following:

iFrame DDDS Parameters

shipIndicator

deliveryTimeFrame

reorderItemsInd

Sample 3D Secure Data

{
   "amount"              : "300",
   "cardHolderName"      : "John Smith",
   "email"               : "[email protected]",
   "shipIndicator"       : "01",
   "deliveryTimeFrame"   : "02",
   "reorderItemsInd"     : "01",
   "currency"            : "840",
   "shippingLine1"       : "2 Main St",
   "shippingLine2"       : "Downtown",
   "shippingLine3"       : "",
   "shippingPostCode"    : "90210",
   "shippingCity"        : "Atlanta",
   "shippingState"       : "GA",
   "shippingCountry"     : "840",
   "billingLine1"        : "2 Main St",
   "billingLine2"        : "Downtown",
   "billingLine3"        : "",
   "billingPostCode"     : "90210",
   "billingCity"         : "Atlanta",
   "billingState"        : "GA",
   "billingCountry"      : "840",
   "clientTransactionId" : "asdf1234"
}

Sample encrypt call

The following example calls the encrypt function with the additional 3DS data.

// Called when user clicks submit on parent page
paymentiFrame.encrypt({
    ddds_params: {
       amount            : "300", // three hundred dollars
       cardHolderName    : "John Smith",
       shipIndicator     : "06", // Travel and Event tickets, not shipped
       deliveryTimeFrame : "01", // Electronic Delivery
       reorderItemsInd   : "01", // First time ordered
   }})
   .success(function (res) {
       console.log("id " + res.id + " token=>" + res.eToken );
   })
   .failure(function (err) {
       console.log("Error: " + err.id + " -> " + JSON.stringify(err, null, 4));
   })
   .invalidInput(function (data) {
       for (var i = 0; i < data.invalidInputs.length; i++) {
           console.log("InvalidInput: " + data.invalidInputs[i].code + ": " + data.invalidInputs[i].field + " -> " + data.invalidInputs[i].message);
       }
   });

If the success callback get triggered, it returns the following object:

{
    "id": "22bd0d27-9b69-5f31-dcf6-bb11c882fb0b",
    "eToken": "DBTFrkuDZpNUmFc-edkeYQCuJihCWtvLW9PGyH5qsd7VZGVMpDTZQXnumV758U_QsCeuEhXxWTTTd7zk0wEnyvFih4DCMlbZ4T_vvzPBrbve3y8ax_cGT5VKIHrUjpr8tbC4YmJzGg6FAzjA5x9y8XzIw9CBMbQ5NZvEIZzT03ni_gbZSjxeorUCRBRnmnTPgQ4LJiil5sbgDbAPYtlcg9xo0eqV6Yp6",
    "masked": {
        "number": "4***********9990",
        "expy": "1225",
        "cvv": "***"
    },
    "ddds_result": {
        "error": null,
        "ddds_version": "2.2.0",
        "ddds_eci": "05",
        "ddds_dstransid": "2abe7b65-45cd-4a58-bcd3-8b10b8f8f50e",
        "ddds_authenticationvalue": "ji+A0S72pd/RFOrr1fwCKXKqDno=",
        "ddds_status": "Y",
        "ddds_attempted": true,
        "ddds_challenged": false,
        "card_brand": "VISA"
    },
    "antiFraud": {
        "device_trans_id": "e32df64a8ad58db99799c81019ab4352add6"
    }
}

Enabling eToken in the Portal settings includes the token in the object above, eliminating the need for the ddds_result data, as these are embedded within the encrypted token itself.

The antiFraud object is included with the Anti-Scoring feature enabled - see Requirements.

QSAPI Transaction

Finally, we can use the eToken in the Bluefin's PayConex® API (QSAPI) request.

📘

Note

When there is the eToken parameter in a QSAPI request, the token overrides the values set for the card_number, card_expiration, and card_verification parameters. For further details on the other supported QSAPI parameters, please refer to the QSAPI Request Format.

curl "https://secure.payconex.net/api/qsapi/3.8/" \
    -X POST \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --header "Cache-Control: no-cache" \
    -d response_format=JSON \
    -d account_id=<replace_account_id> \
    -d api_accesskey=<place_api_accesskey_here> \
    -d tender_type=CARD \ 
    -d transaction_type=SALE \ 
    -d transaction_amount=99.00 \ # Transaction Total
    -d first_name=Joseph \
    -d etoken=<place_token_here> \ # eToken from iFrame encrypt call
    -d custom_id=f04f4fee-91a7-4329-9d65-c228dbd8319a # custom_id for transaction tracing purposes

Hosted Payment Forms

🚧

Note

Before configuring 3D Secure settings for Hosted Payment Forms, make sure to satisfy the Requirements first.

Before reading this implementation option, consider revisiting Hosted Payment Forms.

Enabling on the Hosted Payment Forms

The user must turn on Enable 3D Secure 2.2 Authentication per Hosted Form through the Tools -> Hosted Payment Forms under Security Features. To see this option, of course make sure that the Payment Options check Credit & Debit Card.

📘

Note

The Anti-fraud scoring is also enabled per Hosted Form.

As far as the challenge display option, it is usually none in order to keep the workflow as frictionless as possible. However, this option can be featured as either a pop-up or an overlay. To enable this functionality, please contact Bluefin Technical Support.

The dropdown selections consist of:

Shipping Method

Delivery Time Frame

Upon landing on the Payment page, 3D Secure authentication happens in the background within milliseconds. An end-user enters the card payment information, and upon clicking Process Payment 3D Secure authentication takes place. After the 3D Secure authentication is successful, the 3D Secure data results are used in a transaction request in the same way as the API-based approach.

Agents/Merchants can check the transaction meta-data to see if the transaction was 3D-authenticated. To check that out in action, see Getting 3DS Transaction Data and Create Report.

API

In addition to the regular parameters you provide in your payment request, we recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorization rate.

Some of these objects might be mandatory for the issuer and the card scheme, and not providing them in your payment request might result in a failed authentication.

curl --location --request POST 'https://secure.payconex.net/api/qsapi/3.8' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account_id=180000005404' \
--data-urlencode 'api_accesskey=7c5849b64dc5639d6bbac7ee44b385be' \
--data-urlencode 'response_format=JSON' \
--data-urlencode 'transaction_type=SALE' \
--data-urlencode 'tender_type=CARD' \
--data-urlencode 'card_verification=123' \
--data-urlencode 'card_expiration=1222' \
--data-urlencode 'transaction_amount=55' \
--data-urlencode 'dental_amount=50.85' \
--data-urlencode 'card_number=4264280001234559' \
# 3DS-Authenticated Parameters
--data-urlencode 'ddds_dstransid=d65e93c3-35ab-41ba-b307-767bfc19eae3' \
--data-urlencode 'ddds_authenticationvalue=ANtRo07IKYx4LTvmCzK7IFaMrlY=' \
--data-urlencode 'ddds_eci=05' \
--data-urlencode 'ddds_status=Y' \
--data-urlencode 'ddds_version=2.2.0'

🚧

ddds_dstransid and Amex cards

For Amex cards, usually a separate amexDsTransId is used. Its value has to be passed on in the ddds_dstransid field.

🚧

Note

When a 3DS authentication fails, anti-fraud scoring becomes a factor in deciding whether the transaction should proceed. Anti-fraud scoring can serve as a secondary line of defense when 3DS fails.

Fraud Scoring is a feature on its own and it does not need to be used with 3D Secure. For more, refer to Fraud Scoring.

For Direct API Integration, the device_trans_id parameter is included in the transaction request above.

Reporting

Agents/Merchants have the ability to run reports with transactions that were 3DS protected both via the Portal and RSAPI.

Create Report

PayConex® Custom Reports gives our merchants the flexibility to add 3D Secure data elements so that report is at their fingertips.

In the Portal, this option can be found in the reports tab under Custom Reports.

These are under Additional data fields to include in report to include the 3DS Data Parameters.

Getting 3DS Transaction Data

When getting a transaction meta-data to verify if a transaction was 3DS-authenticated, it is crucial to include these fields as they are not included by default unless we view the complete transaction in the PayConex® Portal.

Request

curl --request POST \
  --url https://cert.payconex.net/api/rsapi/3.8 \
  --data account_id=<replace_account_id> \
  --data api_accesskey=<place_api_accesskey_here> \
  --data response_format=JSON \
  --data transaction_id=000000039466 \
  --data include_fields=ddds_version,ddds_eci,ddds_dstransid,ddds_authenticationvalue,ddds_status,ddds_protected

Response

{
  "api": "RSAPI",
  "version": "3.8",
  "count": 1,
  "transactions": [
    {
      "transaction_id": "000000039466",
      "account_id": "220615031547",
      "authorization_date": "2024-12-17 08:36:05",
      "tender_type": "CARD",
      "transaction_type": "SALE",
      "transaction_amount": 1,
      "ddds_version": "2.2.0",
      "ddds_eci": "05",
      "ddds_dstransid": "2abe7b65-45cd-4a58-bcd3-8b10b8f8f50e", // ID issued by Directory Server
      "ddds_authenticationvalue": "ji+A0S72pd/RFOrr1fwCKXKqDno=",
      "ddds_status": "Y",
      "ddds_protected": "Yes"
    }
  ]
}

For the description of all ddds_* parameters, see 3DS Data Parameters.

Another alternative is to enable the inclusion of 3DS data under RSAPI Options but note that it is then added for each transaction meta-data response.

Test Card Numbers

The following set of test card numbers can be used to evaluate the different ECI values and 3DS statuses. Where the status and ECI are a ? the card number is triggering a challenge, the results will depend on the option selected in the dropdown on the challenge dialog set in the iFrame options.

📘

Note

These cards are intended solely for testing purposes and should only be used in the Testing/Certification environment. They allow merchants and developers to simulate real-life scenarios to gain a better understanding of how 3D Secure operates.

3D Secure 2.0 Test Cards