Configuring EMV 3-D Secure

Introduction

Card brands are enhancing identity checks and verification services as part of the EMV™ 3-D Secure authentication protocol for e-commerce transactions.

Merchants integrated via Hosted Checkout (HCO) Payment Pages can use the new 3-D Secure version 2 solution. Below is the description of the feature and migration steps:

Preparation Steps

To upgrade to 3-D Secure version 2 via Hosted Checkout, merchants need to take the actions described below:

A merchant is responsible for the following steps

• Registration with CardinalCommerce




• 
  General Sales at Cardinal = 1-877-352-8444, salesoperations@cardinalcommerce.com
  




• Extra step for registration with Mastercard for 3-D Secure version 2: A merchant’s current acquiring information (Acquiring BIN/MID) must be uploaded to the Mastercard 2.0 Directory Server which can only be performed by the merchant’s acquirer. The merchant will need to reach out to their acquirer to complete this step.


• 
  Providing the new processing credentials from CardinalCommerce to the E-xact Gateway (via RPM terminal "3-D Secure" tab). RPM user interface will be updated to receive these credentials, see mockup below (update date TBD).
  


• 
  Merchants must code for new fields. Cardinal provides a list, here, of mandatory and conditional fields. Some issuers may require the conditional fields for authentication. These fields will be prepended with “ThreeDS_” for the purpose of the payment page request.
  
  
  

Supported Card Brands

The processing of 3D Secure is done via the following card brands: Visa, Mastercard, American Express, and Discover. The following card brands are processed under the Discover brand: Diners, JCB, Union Pay.

Merchant Setup 

Under the “Merchant Details” menu, select "3-D Secure". 

Merchants that previously used 3-D Secure version 1, will see that the credentials for 3-D Secure version 1 are populated. Support for version 1 credentials will be maintained only to provide a smooth transition to version 2 (e.g. while the merchant waits for Mastercard to update the directory server).

Merchants that are new to 3-D Secure can ignore the left section of this screen (version 1). In this case, merchants are required to use 3-D Secure version 2 from day one.

To enable 3-D Secure version 2, click on the checkmark "Enable 3-D Secure version 2"

Enter the following credentials (credentials provided by CardinalCommerce). Merchants with multiple merchant accounts will have to add the Cardinal credentials under the Merchant Details menu for each.

• Merchant ID


• Transaction Password


• API Identifier


• Organization Unit ID


• API Key

Select a Supported Card brand by clicking the checkbox beside it. Before selecting a card brand, please ensure that the card brand is ready for such processing (please refer to the above notes about card brand registration). 

Make sure to click the "Update" button to save the changes. 

Once this is completed merchants must validate to ensure transaction authentication is working as expected. It is necessary to ensure the ECI value made it to the processor for authentication.

Hosted Checkout

Payment Page Settings 

Merchants that were already using 3-D Secure version 1 do not need to make any changes to their payment page settings.

New merchants need to proceed to set their payment pages settings. Refer to article "Hosted Checkout Payment Pages Integration Manual" 

Please note: "Require Enrollment" checkbox is not relevant to 3-D Secure version 2. 

Transaction Details 

A section called "3-D Secure Details" is added at the bottom of the transaction details screen (refer to screenshot below). 

• Version: shows the version of the 3-D Secure protocol that was used. 


• Directory Server Transaction ID: an ID returned by CardinalCommerce. 


• Enrolled: a field returned by CardinalCommerce.  


• Payer Authentication Result Status: a field returned by CardinalCommerce.  


• Signature Verification: a field returned by CardinalCommerce.  

New Mandatory and Conditional HCO Fields

Exact Payment Pages (HCO) performs EMV 3-D Secure (3DS) authentication via CardinalCommerce. Merchants must now provide several new mandatory and conditional 3DS fields. These fields, found in the following CardinalCommerce guide, are prepended by "ThreeDS_" to form a new set of parameters (see “Examples” section): https://cardinaldocs.atlassian.net/wiki/spaces/CCen/pages/905478187

• 
  The CardinalCommerce fields must be prepended with “ThreeDS_” for the purpose of the HCO Payment Page request. E.g. ThreeDS_ShippingAddress1
  
  
  


• 
  Values passed in the “ThreeDS_” fields will be passed as-is without any modification or trimming.
  

PLEASE NOTE: Transactions missing mandatory—and applicable conditional fields—may fail 3-D Secure authentication. Failed 3-D Secure authentication will cause the transaction to be declined.

List of Ignored CardinalCommerce Fields 

Values in the following fields will be ignored to avoid conflicting or redundant information. Do not include the following “ThreeDS_” fields in the payment page request:

1. ThreeDS_Amount 


2. ThreeDS_CardExpMonth 


3. ThreeDS_CardExpYear 


4. ThreeDS_CardNumber 


5. ThreeDS_CurrencyCode 


6. ThreeDS_DFReferenceId 


7. ThreeDS_MerchantId 


8. ThreeDS_MsgType 


9. ThreeDS_OrderNumber 


10. ThreeDS_PAResPayload 


11. ThreeDS_ProcessorId 


12. ThreeDS_ThreeDSVersion 


13. ThreeDS_TransactionId 


14. ThreeDS_TransactionPwd 


15. ThreeDS_TransactionType 


16. ThreeDS_Version


17. ThreeDS_AcquirerId


18. ThreeDS_AcquirerMerchantId


19. ThreeDS_AcquirerPassword

Support

Any questions regarding these fields should be directed to CardinalCommerce support.

Transactions failing authentication due to missing fields will not be logged or stored by Exact. The cardholder will be shown a page saying “Payment Failed / Try Again.”

Examples

It is important that the HTML form on the merchant’s site specifies method=“POST”.
See examples below:

Digital Goods (HCO)

<form action="https://checkout.e-xact.com/payment" method="post">

  Amount: <input name="x_amount" value="123.45">

  <!-- Regular HCO parameters -->

  <input name="x_login" type="hidden" value="WSP-ABC-1234">

  <input name="x_fp_sequence" type="hidden" value="123456">

  <input name="x_fp_timestamp" type="hidden" value="1628901234">

  <input name="x_fp_hash" type="hidden" value="3d03d15aad9007658a2dada679899ea3">

  <input name="x_show_form" type="hidden" value="PAYMENT_FORM">

  <!-- Examples of 3DS/Cardinal parameters -->

  <input name="ThreeDS_BillingAddress1" type="hidden" value="123 ABC Street">

  <input name="ThreeDS_BillingCity" type="hidden" value="Toronto">

  <input name="ThreeDS_BillingState" type="hidden" value="ON">

  <input name="ThreeDS_BillingPostalCode" type="hidden" value="M9Z9Z9">

  <input name="ThreeDS_BillingCountryCode" type="hidden" value="124">

  <input name="ThreeDS_Email" type="hidden" value="joesample@abcemailaddress.com">

  <input name="ThreeDS_MobilePhone" type="hidden" value="+12341231234">

  <!-- Do not have shipping address for digital goods -->

  <input name="ThreeDS_ShippingMethodIndicator" type="hidden" value="05">

  <!-- Button for customer -->

  <input value="Complete Payment" type="submit">

</form>

Physical Goods (HCO)

<form action="https://checkout.e-xact.com/payment" method="post">

  Amount: <input name="x_amount" value="123.45">

  <!-- Regular HCO parameters -->

  <input name="x_login" type="hidden" value="WSP-ABC-1234">

  <input name="x_fp_sequence" type="hidden" value="123456">

  <input name="x_fp_timestamp" type="hidden" value="1628901234">

  <input name="x_fp_hash" type="hidden" value="3d03d15aad9007658a2dada679899ea3">

  <input name="x_show_form" type="hidden" value="PAYMENT_FORM">

  <!-- Examples of 3DS/Cardinal parameters -->

  <input name="ThreeDS_BillingAddress1" type="hidden" value="123 ABC Street">

  <input name="ThreeDS_BillingCity" type="hidden" value="New York">

  <input name="ThreeDS_BillingState" type="hidden" value="NY">

  <input name="ThreeDS_BillingPostalCode" type="hidden" value="12345">

  <input name="ThreeDS_BillingCountryCode" type="hidden" value="840">

  <input name="ThreeDS_Email" type="hidden" value="joesample@abcemailaddress.com">

  <input name="ThreeDS_MobilePhone" type="hidden" value="+12341231234">

  <input name="ThreeDS_ShippingFirstName" type="hidden" value="Johan">

  <input name="ThreeDS_ShippingLastName" type="hidden" value="Sample">

  <input name="ThreeDS_ShippingAddress1" type="hidden" value="345 DEF Street">

  <input name="ThreeDS_ShippingCity" type="hidden" value="San Diego">

  <input name="ThreeDS_ShippingState" type="hidden" value="CA">

  <input name="ThreeDS_ShippingPostalCode" type="hidden" value="23456">

  <input name="ThreeDS_ShippingCountryCode" type="hidden" value="840">

  <!-- Button for customer -->

  <input value="Complete Payment" type="submit">

</form>

API 

The following are the required API fields for 3-D Secure version 2 transactions.

Please note: for Mastercard the AAV (Accountholder Authentication Value) is sent using the “cavv” field.

Example of API request (JSON). Mastercard 3D Secure version 2 transaction.

{

“gateway_id”:  "XXXXX-XX",

“transaction_type”: "00",

“amount”: "10.25",

“cc_number”: "XXXXXXXXXXXXXXXX", 

“cc_expiry”: "0626",

“cardholder_name”: "John Jones",

“three_d_secure_program_protocol”: "2",

“three_d_secure_directory_server_transaction_id”: “f38e6948-5388-41a6-bca4-b49723c19437”,

“cavv”: “XXXXXXXXX”,

“ecommerce_flag”: “5”

}

Payer Authentication Result Status (PAResStatus)

Encircled in green is the Cardinal Payer Lookup and Authentication Result Statuses (PAResStatus).

Listed below are the possible Lookup Result statuses: 

For "frictionless" 3DS transactions the Authenticate value is shown as "Not Available" (as in the example image provided above). Listed below are the possible Authenticate Result statuses: 

Troubleshooting production issues with CardinalCommerce

Please provide the following information to Cardinal for troubleshooting:

• 
  

  Transaction Amount

  
  


• 
  

  Last four digits of of the credit card

  
  


• 
  

  Transaction date, time, and your terminal time zone.

  
  


• 
  

  CAVV

  
  

Test cards and test cases

Testing can be done in the DEMO environment. 
Test credentials on a merchant account are hard coded. Hence, any test credentials typed into the "3-D Secure" tab on a merchant account will work. 
However, for Production a merchant must use its own Production credentials that are provided by CardinalCommerce.
 

During testing please use only the 3-D Secure v2 test cards. Tests using other test cards will lead to failing transactions. 

Please note, the test cards below are tied to a specific test case. Further details can be found on the CardinalCommerce website: https://cardinaldocs.atlassian.net/wiki/spaces/CCen/pages/903577725/EMV+3DS+Test+Cases

Test case: Successful Frictionless Authentication (Successful frictionless authentication representing the cardholder being authenticated by their Card Issuer)

Expected outcome: transaction processed as 3DS v2.

Visa: 4000000000001000

Mastercard: 5200000000001005

American Express: 340000000001007

Discover: 6011000000001002

Test Case: Failed Frictionless Authentication (Authentication Failed by Card Issuer without Challenge)

expected behaviour: payment page asks for another method of payment

Visa: 4000000000001018

Mastercard: 5200000000001013

American Express: 340000000001015

Discover: 6011000000001010

Test Case: Successful Step Up Authentication (Successful traditional Step Up (Challenge) authentication transaction)

Visa: 4000000000001091

Mastercard: 5200000000001096

American Express: 340000000001098

Discover: 6011000000001093

Test Case: Failed Step Up Authentication (Traditional Step Up (Challenge) authentication transaction with failed cardholder challenge)

expected behaviour: payment page asks for another method of payment

Visa: 4000000000001109

Mastercard: 5200000000001104

American Express: 340000000001106

Discover: 6011000000001101