3D Secure

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.

“3D” refers to the "three domains" which interact using the protocol:

  • Merchant/acquirer domain.
  • Issuer domain.
  • Interoperability domain (payment system/gateway between the other domains).

Authenticated transactions receive a chargeback liability shift and go straight to the issuer. Check this out to understand chargeback codes covered by 3D Secure.

Your 3D Secure implementation options
We provide the following options to support 3D Secure. For more information and detailed instructions, select how you want to integrate:

3D secure sits on the merchant’s payment form and allows the acquiring bank to verify with the issuing bank (cardholder's bank) that the cardholder is, in fact, who they say they are. The authentication happens within milliseconds behind the scenes and starts as soon as the cardholder starts typing their information. The transaction is completed without further shopper interaction.



In addition to the regular parameters you provide on 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' \
--data-urlencode 'ddds_dstransid=d65e93c3-35ab-41ba-b307-767bfc19eae3' \
--data-urlencode 'ddds_authenticationvalue=ANtRo07IKYx4LTvmCzK7IFaMrlY=' \
--data-urlencode 'ddds_eci=1' \
--data-urlencode 'ddds_status=Y' \
--data-urlencode 'ddds_version=2.0.1'


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.

Hosted Payment Forms

3D Secure Configuration

3D Secure will have to be enabled from the Payconex Account Settings page > Security Features.

  • 3DS Enabled
  • PAAY API Access Key - This key is generated by our Bluefin Admin which is unique per agent/merchant at PAAY.
  • PAAY API Secret Key - This is also generated by our Bluefin Admin which is unique per agent/merchant by PAAY.



Currently only the Product/Technology & Ops have access to PAAY Portal to set up a merchant account.

Enabling on the Hosted Payment Forms

Enable 3D Secure 2.2 Authentication will have to be turned on per Hosted Payment Form through the HPF settings page > Security Features

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 happens.

Agents/merchants can check the ‘Transaction Detail’ to see if the transaction was 3D authenticated.

  • 3DS Version - 2.1
  • 3DS ECI - Electronic Commerce Indicator is a code that is returned by the issuing banks and credit card-specific networks to notify a merchant about the authentication of the cardholder and the status of the card holder's issuing bank under the 3D Secure Authentication program.
  • 3DS Transaction ID - Unique Transaction Identifier
  • 3DS Token - Meaningless ciphertext
  • 3DS Protected - Yes/No


3D Secure on iFrame (Configuration & Set up)

3D Secure configuration can be turned on from the Payconex Account Settings page > iFrame options

3DS Enabled

  • Yes - Enable
  • No - Disable

3DS Challenge Indicator

  • No Preference - We suggest our merchants leave preference blank.
  • No Challenge requested - Challenge is never presented to the end-user.
  • Challenge requested - Inform the issuing bank that the challenge is presented to your end-users.
  • Challenge requested mandated - This option dictates that a challenge must be presented to the end-users.

3DS Challenge Display option

  • Overlay iFrame - If the transaction is challenged the bank's dialog will overlay the Payment iFrame. This option is recommended when the Payment iFrame takes up a lot of screen real estate.
  • Pop-up Window - If the transaction is challenged the bank's dialog will appear in a popup window. This option is suggested if the area given to the Payment iFrame is relatively small.

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. 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.

The complete list of fields follows:

  • amount (required) - Transaction total dollar amount.
  • cardHolderName (required) - First name and Last Name of credit card holder.
  • email - Card holder's email address.
  • shipIndicator - Shipping method used to deliver goods:
  • 01 = Ship to cardholder’s billing address.
  • 02 = Ship to another verified address on file with merchant.
  • 03 = Ship to address that is different than the cardholder's billing address.
  • 04 = Ship to Store / Pick-up at local store (Store address shall be populated in shipping address. fields)
  • 05 = Digital goods (includes online services, electronic gift cards and redemption codes).
  • 06 = Travel and Event tickets, not shipped.
  • 07 = Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.).
  • deliveryTimeFrame - When would the goods be delivered:
    01 = Electronic Delivery.
    02 = Same day shipping.
    03 = Overnight shipping.
    04 = Two-day or more shipping.

reorderItemsInd - Is the order new for the customer or has they ordered this item before:
01 = First time ordered
02 = Reordered

currency - ISO 4217 three-digit currency code. Default is 840 (USD)
shippingLine1 - First line of shipping street address
shippingLine2 - Second line of shipping street address
shippingLine3 - Third line of shipping street address
shippingPostCode - Zip Code / Postal Code of shipping address
shippingCity - City of shipping address
shippingState - State of shipping address. Values accepted are the country subdivision code defined in ISO 3166-2. e.g. GA for Georgia
shippingCountry - Country of shipping address. Values accepted are ISO 3166-1 three-digit
country codes. e.g. 840 for the United States
billingLine1 - First line of cardholder street address
billingLine2 - Second line of cardholder street address
billingLine3 - Third line of cardholder street address
billingPostCode - Zip Code / Postal Code
billingCity - City of cardholder address
billingState - State of cardholder address. Values accepted are the country subdivision code defined in ISO 3166-2. e.g. GA for Georgia
billingCountry - Country of cardholder address. Values accepted are ISO 3166-1 three-digit
country codes. e.g. 840 for the United States
clientTransactionId - Optional ID for merchant to correlate with the 3DS transaction

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);


Agents/Merchants also have the ability to run reports with transactions that were 3DS protected.
PayConex Custom Reports gives our merchants the flexibility to add 3D Secure data elements so that report is at their fingertips.

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



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.

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
NOTE: 3D Secure alone will not eliminate all chargebacks.

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.

How is Paay’s 3D Secure service different from other 3DS services?
All 3D Secure services use the same XML messaging security protocol to authenticable a customer. (Examples of other providers are: Verified by Visa, Mastercard Secure Code and AMEX Safekey.)

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 backend. To Demo how this works, please visit our demo checkout page. As you enter your credit card information, you will see the authentication happen (Don't worry, your credit card won't be charged!

*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. Download our One Pager for a detailed explanation on how it works.

Who is Bluefin’s 3D Secure partner?
Bluefin has partnered with Paay.co to offer a 3D Secure solution. PAAY is a leading consumer authentication service for merchants. Their service is simple, secure & seamless to implement. Typically Visa & MC do not work directly with merchants or ISO's to make 3DS accessible; they rely on certified providers like PAAY to service the e-commerce market.
In the US, there are only two certified providers of 3-D Secure, and PAAY is one of them.