Introduction
Card brands are enhancing identity checks and verification services as part of the EMV™ 3-D Secure 2 authentication protocol for e-commerce transactions. (EMV refers to EMV Co., the standards organization, not to be confused with chip-based acquiring)
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:
An important compliance notice about European PSD2 SCA payment authentication regulations: The second Payment Services Directive (PSD2) introduces new requirements for authenticating online payments. These requirements came into effect on 2020-12-31.
What is changing as part of PSD2 SCA?
SCA stands for Strong Customer Authentication. It is a key regulatory mandate included in PSD2 within the European Economic Area (EEA) that requires electronic payments initiated by the buyer to be authenticated by at least two independent factors.
The European Union (EU) passed the SCA mandate to ensure electronic payment methods are carried out in a secure manner to assist the reduction in fraud. It came into force for all European countries effective 2020-12-31, apart from the UK, where the mandate takes effect on 2021-9-14.
EMV 3-D Secure, often referred to as 3-D Secure version 2, is the de facto standard to meet the SCA mandate. Implementing 3-D Secure version 2 will ensure that merchants do not experience disruptions.
(For API integration, please refer to https://support.payeezy.com/hc/en-us/articles/206601408, section "3DS version 2")
Preparation Steps
To upgrade to 3-D Secure version 2 via Hosted Checkout, merchants need to take the actions described below.
Please note: failure to migrate to 3-D Secure version 2 could result in some transactions being declined. Payeezy Gateway provides the integration to the 3-D Secure version 2. However, it is the merchant's responsibility to check which version is needed for its compliance.
3-D Secure via Hosted Checkout is performed using the CardinalCommerce integration.
A merchant is responsible for the following steps
- Registration with CardinalCommerce
- Providing the new processing credentials from CardinalCommerce to Payeezy Gateway (via RPM terminal "3-D Secure" tab).
- Registration with Mastercard for 3-D Secure version 2. 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. Therefore the merchant will need to reach out to their acquirer.
- CardinalCommerce requires the merchant’s American Express SE Number and AIN (American Express Region) as well as the Discover Acquiring BIN and Acquiring MID. CardinalCommerce will load the merchant’s American Express and Discover into the Directory Servers in addition to adding those to the merchant’s Cardinal account.
- Coding to collect and submit Mandatory 3-D Secure fields via the payment page.
Please note:
The existing 3-D Secure version 1 processing credentials from CardinalCommerce are not sufficient for 3-D Secure version 2 processing via Payeezy Gateway (PGW) Hosted Checkout (HCO). Some bank acquirers are not ready for 3DS v2. In this case, CardinalCommerce will failover from 3DS v2 to 3DS v1.
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 for processing of 3D Secure: Diners, JCB, Union Pay.
Terminal Setup
Under the “Terminal” 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. PGW maintains support for version 1 credentials only to provide a smooth transition to version 2, i.e., 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. 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)
- Merchant ID
- Transaction Password
- API Identifier
- Organization Unit ID
- API Key
Select a Supported Card brand by clicking the checkmark 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.
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"
https://support.payeezy.com/hc/en-us/articles/203992129
Section, 3-D Secure Settings.
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.
Mandatory and conditional fields
3D-Secure verification is done via CardinalCommerce. Merchants must provide 3D-Secure fields in the form of new Payment Page "ThreeDS_" parameters which are then included in the request from our gateway to CardinalCommerce. CardinalCommerce defines which of the fields are mandatory/conditional based on 3D-Secure compliance requirements.
PLEASE NOTE: transactions missing mandatory and applicable conditional fields may fail 3D-Secure authentication. Failed 3D-Secure authentication will lead to a declined transaction on our gateway.
CardinalComemerce link to field documentation is here
https://cardinaldocs.atlassian.net/wiki/spaces/CCen/pages/905478187
- The names of these fields begin with "ThreeDS_". When the field is sent to CardinalCommerce, the "ThreeDS_" is dropped from the field name to keep the field names according to CardinalCommerce's integration manual. For example, the value provided by the merchant in a parameter called ThreeDS_ProductCode is submitted as ProductCode to CardinalCommerce. The value of ThreeDS_AuthenticationIndicator is submitted as AuthenticationIndicator to CardinalCommerce and so on.
- However merchants will not be able to overwrite the values for the existing implementation of what is already submitted to CardinalCommerce (E.g., Amount, CurrencyCode, OrderNumber, etc). Refer to the ignored list below.
- The values passed via the ThreeDS_ fields will be passed as is without any modification or trimming.
List of ignored CardinalCommerce fields
Our gateway automatically populates some of the CardinalCommerce fields based on the information collected from the terminal setup, payment page, and so on. Hence, to avoid conflicting and redundant information, we ignore information from the following ThreeDS_ fields. The following fields, when provided by the merchant with ThreeDS_ will be ignored. No need for the merchant to populate them.
- ThreeDS_Amount
- ThreeDS_CardExpMonth
- ThreeDS_CardExpYear
- ThreeDS_CardNumber
- ThreeDS_CurrencyCode
- ThreeDS_DFReferenceId
- ThreeDS_MerchantId
- ThreeDS_MsgType
- ThreeDS_OrderNumber
- ThreeDS_PAResPayload
- ThreeDS_ProcessorId
- ThreeDS_ThreeDSVersion
- ThreeDS_TransactionId
- ThreeDS_TransactionPwd
- ThreeDS_TransactionType
- ThreeDS_Version
- ThreeDS_AcquirerId
- ThreeDS_AcquirerMerchantId
- ThreeDS_AcquirerPassword
Examples
Digital Goods (HCO)
<form action="https://checkout.globalgateaye4.firstdata.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_PostalCode" 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">
<!-- 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.globalgateaye4.firstdata.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_PostalCode" 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>
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 on 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 (Diners): 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 (Diners): 6011000000001010
Test Case: Successful Step Up Authentication (Successful traditional Step Up (Challenge) authentication transaction)
Visa: 4000000000001091
Mastercard: 5200000000001096
American Express: 340000000001098
Discover (Diners): 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 (Diners): 6011000000001101