3D Secure 2.0 Technical Integration Guide

Important: the following functionalities are not yet available on the test or live environment! More details to follow soon.

PIPE

For users of PIPE, minimal additional effort is required compared to the current integration. The workflow is identical to the current 3D Secure 1.0 implementation. The widget will handle the entire additional communication and will be responsible for collecting required browser based information automatically. Following data must be collected by the merchant and send in via

  • Server/Server, create checkoutId
  • being collected by adding additional input fields to the payment widget (see here)
Field name Mandatory/Optional Source when using the widget
billing.city Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)
billing.country Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)
billing.street1 Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)
billing.postcode Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)
customer.email Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)
customer.givenName Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)
customer.surname Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API)

Server to Server

For users who are integrating via server to server will need to follow EMVCo's guidelines on the frontend integration. Please follow the steps described below:

  1. Prepare your front-end and follow EMVCo's recommendation (see Section 4 "EMV 3-D Secure User Interface Templates, Requirements, and Guidelines" here) on how the authentication window should be shown in the webshop (eg. in and iframe or in a lightbox).
  2. Prepare your back-end and send following additional information along with the payment information:
Field API Field name Description
Accept header customer.browser.acceptHeader HTTP accept header sent from the cardholder's browser.
Language customer.browser.language The cardholder's browser language.
Screen height customer.browser.screenHeight This field contains the total height of the cardholder's screen in pixels.
Screen width customer.browser.screenWidth This field contains the total width of the cardholder's screen in pixels.
Browser timezone customer.browser.timezone This field contains the cardholder's browser local timezone.
User agent customer.browser.userAgent This field contains the exact content of the HTTP User-Agent header.
IP address customer.browser.ipAddress IP address of the cardholder's browser.
Java enabled customer.browser.javaEnabled true/false - Ability of the cardholder's browser to execute Java.
Screen color depth customer.browser.screenColorDepth This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.
Authentication window size customer.browser.challengeWindow

Size of the authentication iframe which will render the ACS authentication front-end to the shopper for interaction.

Please send an Integer between 1-5. The integer corresponds to one the following resolutions:

1 2 3 4 5
250 x 400 390 x 400 500 x 60 600 x 400 Full screen

Server to Server response

Server to Server response
{
	"id": "8ac7a4a0686138d701687eebfbc74747",
	"paymentType": "DB",
	"paymentBrand": "VISA",
	"result": {
		"code": "000.200.000",
		"description": "transaction pending"
	},
	"resultDetails": {
		"clearingInstituteName": "Elavon-euroconex_UK_Test"
	},
	"card": {
		"bin": "411111",
		"last4Digits": "1111",
		"holder": "Jane Jones",
		"expiryMonth": "05",
		"expiryYear": "2020"
	},
	"redirect": {
		"url": "https://test.planetpaymentgateway.com/v1/threeDSecure/execute",
		"parameters": [{
			"name": "name",
			"value": "value"
		}],
		"preconditions": [{
			"origin": "iframe#hidden",
			"waitUntil": "iframe#onload",
			"description": "Hidden iframe post for 3D Secure 2.0",
			"method": "POST",
			"url": "methodURL",
			"parameters": [{
				"name": "methodData",
				"value": "methodData"
			}]
		}]
	},
	"risk": {
		"score": "100"
	},
	"buildNumber": "deebd8c9af7d84ddee98c38b7f4afcc814012b5b@2019-01-22 13:58:00 +0000",
	"timestamp": "2019-01-24 08:13:41+0000",
	"ndc": "8a8294184e736012014e78bb38911687_0557df43f75643d19479440642979e00"
}

  1. Open a hidden iframe and post data to the methodURL

    <form name='' action='call.url' method='POST'>
    	<INPUT type='hidden' name='preconditions.parameters[].name' value='preconditions.parameters[].value'>
    </form>
    <script>
    	window.onload = submitForm;
    	function submitForm() { downloadForm.submit(); }
    </script>
  2. Redirect the shopper within and iframe to the redirect URL if onLoad event received from 1.

    <form name='' action='redirect.URL' method='POST'>
    	<INPUT type='hidden' name='redirect.parameters[].name' value='redirect.parameters[].value'>
    </form>
    <script>
    	window.onload = submitForm;
    	function submitForm() { downloadForm.submit(); }
    </script>

Fields required for 3D Secure 2.0

Please note that in order to have a better rate of successful risk-checks during the risk based authentication, it is recommended to send as many fields as possible. This will positively affect the number of frictionless flows.

Source is the cardholder or cardholder's environment

Field name Mandatory/Optional Source when using the widget Source when integrating via Server-to-Server API
card.expiryMonth Mandatory Cardholder (via widget) Cardholder (via API)
card.expiryYear Mandatory Cardholder (via widget) Cardholder (via API)
card.number Mandatory Cardholder (via widget) Cardholder (via API)
billing.city Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
billing.country Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
billing.street1 Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
billing.postcode Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
customer.email Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
customer.workPhone Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
customer.givenName Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
customer.surname Recommended. Not required if market or regional mandate restricts sending this information. Cardholder (via widget or API) Cardholder (via API)
amount Mandatory Payment (via API) Payment (via API)
currency Mandatory Payment (via API) Payment (via API)
shipping.city Optional Cardholder (via widget or API) Cardholder (via API)
shipping.country Optional Cardholder (via widget or API) Cardholder (via API)
shipping.street1 Optional Cardholder (via widget or API) Cardholder (via API)
shipping.street2 Optional Cardholder (via widget or API) Cardholder (via API)
shipping.postcode Optional Cardholder (via widget or API) Cardholder (via API)
shipping.state Optional Cardholder (via widget or API) Cardholder (via API)
billing.street2 Optional Cardholder (via widget or API) Cardholder (via API)
billing.street2 Optional Cardholder (via widget or API) Cardholder (via API)
billing.state Optional Cardholder (via widget or API) Cardholder (via API)
customer.phone Optional Cardholder (via widget or API) Cardholder (via API)
customer.workPhone Optional Cardholder (via widget or API) Cardholder (via API)
customer.mobile Optional Cardholder (via widget or API) Cardholder (via API)
customer.browser.acceptHeader Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.language Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.screenHeight Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.screenWidth Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.timezone Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.userAgent Mandatory Automatically collected by the widget Merchant should collect and send via API
customer.browser.ipAddress Optional Automatically collected by the widget Merchant should collect and send via API
customer.browser.javaEnabled Optional Automatically collected by the widget Merchant should collect and send via API
customer.browser.screenColorDepth Optional Automatically collected by the widget Merchant should collect and send via API
customer.browser.challengeWindow Optional Automatically collected by the widget Merchant should collect and send via API

Merchant related fields configured in the gateway

Field name Mandatory/Optional Comment
Merchant category code Mandatory
Merchant country code Mandatory
Merchant name Mandatory Merchant name assigned by the Acquirer or Payment System.
Merchant ID Mandatory Acquirer-assigned Merchant identifier.
Requestor ID Mandatory DS assigned 3D Secure Requestor identifier.
Requestor Name Mandatory DS assigned 3D Secure Requestor name.
Requestor URL Mandatory Fully qualified URL of 3D Secure Requestor website or customer care site.


Optional settings

Merchants have the possibility to set the preference of a transaction being challenged or not. This really is only a preference, and won't guarantee that the issuer will or will not request a challenge from the cardholder. It is up to the issuer if they consider the merchant's preference, and if they include it when they assess the risk of the transaction.

For example when a card is being stored for later use (eg. for One click checkout), a challenge may be requested by the merchant. In another example, there might be some regional mandates that certain transactions have to be challenged and the merchant should ask for a mandated challenge.

Send the field threeDSecure.challengePreference with one of the following values:

Value Challenge Preference Description
01 No preference The merchant has no preference, and fully trust the issuer to ask a challenge from the cardholder.
02 No challenge requested The merchant prefers that the cardholder is not authenticated by the issuer, and only the frictionless flow applies
03 Challenge requested: 3D Secure Requestor Preference The merchant prefers that the cardholder is authenticated by the issuer.
04 Challenge requested: Mandate The cardholder authentication is mandated (eg. by regional mandates)

The field threeDSecure.challengePreference is optional. If not sent, the value "01 - No preference" applies by default.

Information about the cardholder's account and history with the merchant

The following fields are not mandatory, but it is strongly recommended to send them. They are affecting the accuracy of the issuer's risk check, and will result in more frictionless flows.

The field values below can be collected by the 3D Secure Requestor* about the cardholders activity on their webshop.

*3D Secure Requestor denotes the merchant

Field name Description
customParameters[ReqAuthMethod]

Method used by the Cardholder to authenticate to the 3D Secure Requestor.

Contains optional information about how the cardholder authenticated during login to their 3D Secure Requestor account.

Possible values are:

01 No authentication occurred (i.e. cardholder "logged in" as guest)
02 Login to the cardholder account at the merchant system using cardholder's own credentials
03 Login to the cardholder account at the merchant system using federated ID
04 Login to the cardholder account at the merchant system using issuer credentials
05 Login to the cardholder account at the merchant system using third-party authentication
06 Login to the cardholder account at the merchant system using FIDO Authenticator
customParameter[ReqAuthTimestamp]

Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Part of the 3D Secure Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their account.

customParameter[PriorAuthMethod]

Mechanism used by the Cardholder to previously authenticate to the 3D Secure Requestor.

Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

Possible values are:

01 Frictionless authentication occurred by ACS
02 Cardholder challenge occurred by ACS
03 ACS verified
04 Other issuer methods
customParameters[PriorAuthTimestamp]

Date and time in UTC of the prior cardholder authentication. Accepted date format is YYYYMMDDHHMM.

Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

customParameter[PriorReference]

This data element provides additional information to the ACS to determine the best approach for handling a request. It contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).

Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

customParameter[AccountId] Additional information about the account optionally provided by the 3D Secure Requestor in AReq messages.
customParameter[AccountAgeIndicator]

Length of time that the cardholder has had the account with the 3D Secure Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameter[AccountChangeDate] Date that the cardholder's account with the 3D Secure Requestor was last changed. Accepted date format is YYYYMMDD.
customParameter[AccountChangeIndicator]

Length of time since the cardholder's account information with the 3D Secure Requestor was last changed.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameter[AccountDate] Date that the cardholder opened the account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameter[AccountPasswordChangeDate] Date that cardholder's account with the 3D Secure Requestor had a password change or account reset. Accepted date format is YYYYMMDD.
customParameter[AccountPasswordChangeIndicator] Indicates the length of time since the cardholder's account with the 3D Secure Requestor had a password change or account reset.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameter[AccountPurchaseCount] Number of purchases with this cardholder account during the previous six months.
customParameter[AccountProvisioningAttempts] Number of Add Card attempts for the account in the last 24 hours.
customParameter[AccountDayTransactions] Number of transactions (successful and abandoned) for this cardholder account with the 3D Secure Requestor across all payment accounts in the previous 24 hours.
customParameter[AccountYearTransactions] Number of transactions (successful and abandoned) for this cardholder account with the 3D Secure Requestor across all payment accounts in the previous year.
customParameter[PaymentAccountAge] Date that the payment account was enrolled in the cardholder's account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameter[PaymentAccountAgeIndicator]

Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3D Secure Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameter[ShipAddressUsageDate] Date when the shipping address used for this transaction was first used with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameter[ShipAddressUsageIndicator]

Indicates the length of time since the shipping address used for this transaction was first used with the 3D Secure Requestor.

Possible values are:

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
customParameter[ShipIndicator]

Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not their general business. If one or more items are included in the sale, the Shipping Indicator code for the physical goods is used, or if all digital goods, the Shipping Indicator code that describes the most expensive item.

Possible values are:

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.)
customParameter[ShipNameIndicator]

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

Possible values are:

01 Account Name identical to shipping Name
02 Account Name different than shipping Name
customParameter[SuspiciousAccountActivity]

Indicates whether the 3D Secure Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

Possible values are:

01 No suspicious activity has been observed
02 Suspicious activity has been observed