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". 
Screen_Shot_2021-09-17_at_10.02.55_AM.png

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.  

EMVTXN.jpg

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.

API field name

Purpose

Valid values

“three_d_secure_program_protocol” 

Determines the 3D Secure protocol version to use. 

Can be either “1” or “2”. 

 

 

 

1 = 3D Secure version 1 

2 = 3D Secure version 2

If any value other than

1 or 2 is provided, this field will be discarded, and this information will not be provided to Mastercard. 

“three_d_secure_directory_server_transaction_id” 

This is a universally unique Transaction ID that the merchant must provide.

This ID is sent back to merchant by Cardinal

Note: DO NOT MANIPULATE this value in any way.

f38e6948-5388-41a6-bca4-b49723c19437

“cavv”

3-D Secure cryptogram. Populate with the value returned from Cardinal.

AZADAWczgZABFAmVlTOBELigIMI=

“xid”

3-D Secure cryptogram. The XID value is only returned for American Express transactions

VkM0MXAwOGhjMGxuaUcxU1VtNjA

 

“ecommerce_flag”

Electronic Commerce Indicator

5 = Fully Authenticated

6 = Authentication Attempted
7 = Not a 3-D Secure transaction

 

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”

}

 

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

Testing can be done in the DEMO environment. 

3-D Secure version 2 test cards

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



Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk