COPYandPAY

For users of COPYandPAY, 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 Required unless market or regional mandate restricts sending this information. Cardholder (via widget or API)
billing.country Required unless market or regional mandate restricts sending this information. Cardholder (via widget or API)
billing.street1 Required unless market or regional mandate restricts sending this information. Cardholder (via widget or API)
billing.postcode Required unless market or regional mandate restricts sending this information. Cardholder (via widget or API)
customer.email Required unless market or regional mandate restricts sending this information. Cardholder (via widget or API)
card.holder Required unless market or regional mandate restricts sending this information. Cardholder (via widget or API)
FIELD NAME MANDATORY/OPTIONAL SOURCE WHEN USING THE WIDGET
billing.city
Required unless market or regional mandate restricts sending this information.
Cardholder (via widget or API)
billing.contry
Required unless market or regional mandate restricts sending this information.
Cardholder (via widget or API)
billing.street1
Required unless market or regional mandate restricts sending this information.
Cardholder (via widget or API)
billing.postcode
Required unless market or regional mandate restricts sending this information.
Cardholder (via widget or API)
customer.email
Required unless market or regional mandate restricts sending this information.
Cardholder (via widget or API)
card.holder
Required unless 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:
FieldAPI Field nameDescriptionLength/Format/Values
Accept headercustomer.browser.acceptHeaderHTTP accept header sent from the cardholder’s browser.Length: Variable, maximum 2048 characters JSON Data Type: String Value accepted: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates
Languagecustomer.browser.languageThe cardholder’s browser language.Length: Variable, 1–8 characters JSON Data Type: String
Screen heightcustomer.browser.screenHeightThis field contains the total height of the cardholder’s screen in pixels.Length: Variable, 1–6 characters JSON Data Type: String
Screen widthcustomer.browser.screenWidthThis field contains the total width of the cardholder’s screen in pixels.Length: Variable, 1–6 characters JSON Data Type: String
Browser timezonecustomer.browser.timezoneThis field contains the cardholder’s browser local timezone.Length: 1–5 characters JSON Data Type: String Value accepted: Value is returned from the getTimezoneOffset() method.
User agentcustomer.browser.userAgentThis field contains the exact content of the HTTP User-Agent header.Length: Variable, maximum 2048 characters JSON Data Type: String Value accepted: Note: If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
IP addresscustomer.ipIP address of the cardholder’s browser.Length: Variable, maximum 45 characters JSON Data Type: String Value accepted: IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 to 255. Example IPv4 address: 1.12.123.255 IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets. The groups are separated by colons (:). Example IPv6 address:2011:0db8:85 a3:0101:0101:8a2e:03 70:7334
Java enabledcustomer.browser.javaEnabledtrue/false – Ability of the cardholder’s browser to execute Java.JSON Data Type: Boolean Values accepted: • true • false
Javascript enabledcustomer.browser.javascriptEnabledtrue/false – Ability of the cardholder’s browser to execute JavaScriptJSON Data Type: Boolean Values accepted: • true • false
Screen color depthcustomer.browser.screenColorDepthThis field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.Length: 1–2 characters JSON Data Type: String Values accepted: 1 = 1 bit • 4 = 4 bits • 8 = 8 bits • 15 = 15 bits • 16 = 16 bits • 24 = 24 bits • 32 = 32 bits • 48 = 48 bits
Authentication window sizecustomer.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:

12345
250 x 400390 x 400500 x 600600 x 400Full screen
 

Server to Server Examples

Request
entityId=8ac7a49f6e4a18ae016e4b8b4c4b2146
amount=12.00
currency=EUR
paymentBrand=VISA
paymentType=PA
merchantTransactionId=order99234
transactionCategory=EC
card.number=4000000000000010
card.expiryMonth=12
card.expiryYear=2025
card.cvv=123
card.holder=John Smith
merchant.name=MerchantCo
merchant.city=Munich
merchant.country=DE
merchant.mcc=5399
shopperResultUrl=https://merchant.org
customer.ip=192.168.0.1
customer.browser.acceptHeader=text/html
customer.browser.screenColorDepth=48
customer.browser.javaEnabled=false
customer.browser.language=de
customer.browser.screenHeight=1200
customer.browser.screenWidth=1600
customer.browser.timezone=60
customer.browser.challengeWindow=4
customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)
testMode=EXTERNAL
Intermediate Response
{
    "id": "8ac7a4a0686138d701687eebfbc74747",
    "paymentType": "DB",
    "paymentBrand": "VISA",
    "result": {
        "code": "000.200.000",
        "description": "transaction pending"
    },
    "resultDetails": {
        "clearingInstituteName": "CI_Test"
    },
    "card": {
        "bin": "411111",
        "last4Digits": "1111",
        "holder": "Jane Jones",
        "expiryMonth": "05",
        "expiryYear": "2020"
    },
    "redirect": {
        "url": "https://test.como.world/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": "threeDSMethodData",
                "value": "methodData"
            }]
        }]
    },
    "risk": {
        "score": "100"
    },
    "buildNumber": "deebd8c9af7d84ddee98c38b7f4afcc814012b5b@2019-01-22 13:58:00 +0000",
    "timestamp": "2019-01-24 08:13:41+0000",
    "ndc": "8a8294174b7ecb28014b9699220015ca_0557df43f75643d19479440642979e00"
}

Final Response

{
  "id":"8ac7a49f6e4a18ae016e4b8b4c4b2146",
  "paymentType":"PA",
  "paymentBrand":"VISA",
  "amount":"12.00",
  "currency":"EUR",
  "result":{
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails":{
    "ExtendedDescription":"Approved",
    "AcquirerResponse":"00",
  },
  "card":{
    "bin":"400000",
    "last4Digits":"0044",
    "expiryMonth":"12",
    "expiryYear":"2025"
  },
  "threeDSecure":{
    "eci":"05",
    "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version":"2.1.0",
    "dsTransactionId":"91caca63-5c4e-4aa2-a3f1-b4d418972de8",
    "acsTransactionId":"7055d78e-eb35-46e7-8c4e-56e15092b5f5",
  },
  "buildNumber":"7810ceecdd913cd9c4807becb99b89ce68454900@2019-11-08 12:20:52 +0000",
  "timestamp":"2019-11-08 15:05:42+0000",
  "ndc":"8ac7a4c76dd857ea016dda2ea6970684_3ba4c7691f854354906b2f6c402840e7"
}

How to handle the responses

Method Data and Method URL are not always returned by the issuer. It is an optional step, but if it’s returned it’s important to handle it properly.

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

<form name='' action='preconditions.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

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 nameMandatory/OptionalSource when using the widgetSource when integrating via Server-to-Server APIFormat, Length
card.expiryMonthMandatoryCardholder (via widget)Cardholder (via API)Length: 2 characters
Format: numeric
card.expiryYearMandatoryCardholder (via widget)Cardholder (via API)Length: 4 characters
Format: numeric
card.numberMandatoryCardholder (via widget)Cardholder (via API)Length: Variable, 13-19
Format: numeric
billing.cityRequired unless market or regional mandate restricts sending this information.Cardholder (via widget or API)Cardholder (via API)Length: Variable, 2–45 characters
Format: String with values accepted indicated below
billing.countryRequired unless market or regional mandate restricts sending this information.Cardholder (via widget or API)Cardholder (via API)Length: 2 characters
Format: [A-Z]{2}
billing.street1Required unless market or regional mandate restricts sending this information.Cardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 50 characters
Format: String
billing.postcodeRequired unless market or regional mandate restricts sending this information.Cardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 16 characters
Format: String
customer.emailRequired unless market or regional mandate restricts sending this information.Cardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 128 characters
Format: String
card.holderRequired unless market or regional mandate restricts sending this information.Cardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 128 characters
Format: String
amountMandatoryPayment (via API)Payment (via API)Length: Variable, maximum 12 characters
Format: Numeric with 2 minor units after the decimal point
Example: 123.00
currencyMandatoryPayment (via API)Payment (via API)Length: 3 characters
Format: ISO 4217 A3 currency code
shipping.cityOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 50 characters
Format: String
shipping.countryOptionalCardholder (via widget or API)Cardholder (via API)Length: 3 characters
Format: ISO 3166-1 A2 country code
shipping.street1OptionalCardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 50 characters
Format: String
shipping.street2OptionalCardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 50 characters
Format: String
shipping.postcodeOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 16 characters
Format: String
shipping.stateOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable: maximum 3 characters
Format: Should be the country subdivision code defined in ISO 3166-2
billing.street2OptionalCardholder (via widget or API)Cardholder (via API)Length: Variable, maximum 50 characters
Format: String
billing.stateOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable: maximum 3 characters
Format: Should be the country subdivision code defined in ISO 3166-2
customer.phoneOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable: maximum 20 characters
Format: +ccc-nnnnnnnn
Where:
+ sign is optional
cc – country code, maximum 3 characters
“-” – mandatory character
nnnnnnnnnn – phone number without the country code, maximum 15 characters
customer.workPhoneOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable: maximum 20 characters
Format: +ccc-nnnnnnnn
Where:
+ sign is optional
cc – country code, maximum 3 characters
“-” – mandatory character
nnnnnnnnnn – phone number without the country code, maximum 15 characters
customer.mobileOptionalCardholder (via widget or API)Cardholder (via API)Length: Variable: maximum 20 characters
Format: +ccc-nnnnnnnn
Where:
+ sign is optional
cc – country code, maximum 3 characters
“-” – mandatory character
nnnnnnnnnn – phone number without the country code, maximum 15 characters
customer.browser.acceptHeaderMandatoryAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, maximum 2048 characters
Format: String
customer.browser.languageMandatoryAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, 1–8 characters
Format: String
Returned from navigator.language property.
customer.browser.screenHeightMandatory when customer.browser.javascriptEnabled = true; otherwise OptionalAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, 1–6
Format: Numeric
Value is returned from the screen.height property
customer.browser.screenWidthMandatory when customer.browser.javascriptEnabled = true; otherwise OptionalAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, 1–6
Format: Numeric
Value is returned from the screen.width property
customer.browser.timezoneMandatory when customer.browser.javascriptEnabled = true; otherwise OptionalAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, 1–5 characters
Format: Numeric
Value is returned from the getTimezoneOffset() method.
customer.browser.userAgentMandatoryAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, maximum 2048 characters
Format: String
customer.ipOptionalAutomatically collected by the widgetMerchant should collect and send via APILength: Variable, maximum 45 characters
Format: IPv4 address
Example: 1.12.123.255
customer.browser.javaEnabled3DS 2.1 : Mandatory
3DS 2.2: Mandatory when customer.browser.javascriptEnabled = true; otherwise Optional
Automatically collected by the widgetMerchant should collect and send via APIValues accepted:
• true
• false
Value is returned from the navigator.javaEnabled property.
customer.browser.javascriptEnabledMandatoryAutomatically collected by the widgetMerchant should collect and send via APIValues accepted:
• true
• false
customer.browser.screenColorDepth3DS 2.1 : Mandatory
3DS 2.2: Mandatory when customer.browser.javascriptEnabled = true; otherwise Optional
Automatically collected by the widgetMerchant should collect and send via APILength: 1–2 characters
Format: String
Values accepted:
• 1 = 1 bit
• 4 = 4 bits
• 8 = 8 bits
• 15 = 15 bits
• 16 = 16 bits
• 24 = 24 bits
• 32 = 32 bits
• 48 = 48 bits
customer.browser.challengeWindowOptionalAutomatically collected by the widgetMerchant should collect and send via APILength: 2 characters
Values accepted:
• 01 = 250 x 400
• 02 = 390 x 400
• 03 = 500 x 600
• 04 = 600 x 400
• 05 = Full screen
threeDSecure.amountOptionalSent via the APISent via the APILength: Variable, maximum 12 characters
Format: Numeric with 2 minor units after the decimal point
Example: 123.00
threeDSecure.currencyOptionalSent via the APISent via the APILength: 3 characters
Format: ISO 4217 A3 currency code

Authentication amount and currency

In some cases the amount and/or currency that is used in the authentication can be different from the one that will be used in the payment later. For example the payment amount might not be known at the time of the authentication, or the merchant would like to authenticate the shopper for the full amount when the payment will be done in multiple installments.

If the authentication amount and the payment amount are different, then the authentication amount and currency can be sent in a separate field:

threeDSecure.amountAmount for which the shopper will be authenticated for.
threeDSecure.currencyCurrency for which the shopper will be authenticated for.

Please note that payment amount and currency are still mandatory fields for any payment request. If there are no authentication amount and currency defined then the shopper will be authenticated with the payment amount and currency.

 

Additional settings

3DS Challenge Indicator and MIT agreements

The merchants have the possibility to set the preference of a transaction being challenged or not. This 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 to consider the merchant’s preference during the risk assessment of the transaction. As an example, regional mandates might require transactions to be challenged and the merchant should ask for a mandated challenge. Thus the merchants have the option to send the field threeDSecure.challengeIndicator with one of the following values: Send the field threeDSecure.challengeIndicator with one of the following values:

ValueChallenge PreferenceDescription
01No preferenceThe merchant has no preference, and fully trust the issuer to ask a challenge from the cardholder.
02No challenge requestedThe merchant prefers that the cardholder is not authenticated by the issuer, and only the frictionless flow applies
03Challenge requested: 3D Secure Requestor PreferenceThe merchant prefers that the cardholder is authenticated by the issuer.
04Challenge requested: MandateThe cardholder authentication is mandated (eg. by regional mandates)
Note: Merchants performing recurring payments are required to have a merchant-initiated transaction (MIT) agreement with the cardholder. This grants the merchant permission to store the cardholder’s card data for future transactions when the cardholder is not present. The following requirements apply to these MIT agreements:
  • MIT agreements must have an originating cardholder-initiated transaction (CIT).
  • The initial CIT payment request must go through strong customer authentication (SCA).
  • Scheme regulations mandate that merchants must populate threeDSecure.challengeIndicator with value 04 when sending the initial CIT; this forces the issuer to apply SCA.
If these requirements are not met, merchants are likely to experience payment failures for future MIT requests as a result of SCA not being applied.
05No challenge requestedTransactional risk analysis is already performed
Note: Only available in 3DS 2.2
06No challenge requestedData share only
Note: Only available in 3DS 2.2
07No challenge requestedStrong consumer authentication is already performed
Note: Only available in 3DS 2.2
08No challenge requestedUtilize whitelist exemption if no challenge required
Note: Only available in 3DS 2.2
09Challenge requestedWhitelist prompt requested if challenge required
Note: Only available in 3DS 2.2

Note: For initial 3DS 2 CIT payment requests and any 3DS 2 transactions with field createRegistration set to true, field ChallengeIndicator will be populated a default value of “04 – Challenge Requested Mandate”. This default value will only be populated if the merchant has not populated this field themselves; any merchant-provided values will not be overridden.

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 nameDescription
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:

01No authentication occurred (i.e. cardholder “logged in” as guest)
02Login to the cardholder account at the merchant system using cardholder’s own credentials
03Login to the cardholder account at the merchant system using federated ID
04Login to the cardholder account at the merchant system using issuer credentials
05Login to the cardholder account at the merchant system using third-party authentication
06Login to the cardholder account at the merchant system using FIDO Authenticator
customParameters[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.

customParameters[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:

01Frictionless authentication occurred by ACS
02Cardholder challenge occurred by ACS
03ACS verified
04Other 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.

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

customParameters[PriorAuthData]

This data element contains DS Transaction ID for a prior authenticated transaction as a part of a 3DS Requestor Initiated (3RI) transaction and an AAV Refresh transaction. This parameter helps to improve the ACS chances of approving the transaction linked to a previously authenticated transaction. An AAV Refresh transaction in 3DS 2.1 request must populate the DS Transaction ID of the original authentication transaction that is being refreshed.

Format of the 3DS Requestor Prior Transaction Authentication Data is defined in a JSON Data Type: String. Example: customParameters[PriorAuthData]=dsTransID: 9aed2dc3-4473-4bb8-a763-7bac4b40de3a. It allows up to 2048 characters. Incorrectly formatting could result in processing error.

customParameters[AAVRefresh]

Mastercard generates an Account holder Authentication Values (AAV) for every successfully authenticated payment transaction since 3DS 2.1. Mastercard retention and validity period for an AAV is 10-90 days. AAV Refresh capability allows merchants to request a ‘refreshed’ AAV using a non-payment (NPA) request from the issuer ACS for their previously fully authenticated transaction. Send DS Transaction ID of previously authenticated transaction in customParameters[PriorAuthData].

Possible values: true/false

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

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

Possible values are:

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

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

Possible values are:

01Created during this transaction
02Less than 30 days
0330-60 days
04More than 60 days
customParameters[AccountDate]Date that the cardholder opened the account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameters[AccountPasswordChangeDate]Date that cardholder’s account with the 3D Secure Requestor had a password change or account reset. Accepted date format is YYYYMMDD.
customParameters[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:

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

01No account (guest check-out)
02Created during this transaction
03Less than 30 days
0430-60 days
05More than 60 days
customParameters[ShipAddressUsageDate]Date when the shipping address used for this transaction was first used with the 3D Secure Requestor. Accepted date format is YYYYMMDD.
customParameters[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:

01No account (guest check-out)
02Created during this transaction
03Less than 30 days
0430-60 days
05More than 60 days
customParameters[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:

01Ship to cardholder’s billing address
02Ship to another verified address on file with merchant
03Ship 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)
05Digital goods (includes online services, electronic gift cards and redemption codes)
06Travel and Event tickets, not shipped
07Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)
customParameters[ShipNameIndicator]

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

Possible values are:

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

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

Possible values are:

01No suspicious activity has been observed
02Suspicious activity has been observed
customParameters[TransactionType]

Identifies the type of transaction being authenticated.

Possible values are:

01Goods / Service Purchase
03Check Acceptance
10Account Funding
11Quasi-Cash Transaction
28Prepaid Activation and Load
customParameters[DeliveryTimeframe]

Indicates the merchandise delivery timeframe.

Possible values are:

01Electronic Delivery
02Same Day Shipping
03Overnight Shipping
04Two-day or more shipping
customParameters[DeliveryEmailAddress]

For Electronic delivery, the email address to which the merchandise was delivered.

customParameters[ReorderItemsIndicator]

Indicates whether the cardholder is reordering previously purchased merchandise.

Possible values are:

01First time ordered
02Reordered
customParameters[PreOrderPurchaseIndicator]

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

Possible values are:

01Merchandise available
02Future availability
customParameters[PreOrderDate]

For a pre-ordered purchase, the expected date that the merchandise will be available.
Date format = YYYYMMDD

customParameters[GiftCardAmount]

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

customParameters[GiftCardCurrency]

For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.

customParameters[GiftCardCount]

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

Response fields

In the returned response there are two places where 3D Secure related response values can be present. In the “threeDSecure” object we store the values that are not brand specific and can be returned by any card brand and issuer. In the “resultDetails” object we store the brand specific values if the scheme directory server returns such value.

Values returned in the threeDSecure object

ValueDescription
eciPayment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.
verificationIdPayment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication.
versionVersion of the 3D Secure that was used for authentication
flowIndicates the user flow that was applied during the authentication: challenge or frictionless
dsTransactionIdUniversally unique transaction identifier assigned by the DS to identify a single transaction.
challengeMandatedIndicatorIndication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.
authenticationTypeAuthentication approach that the ACS used to authenticate the Cardholder for this specific transaction.
acsTransactionIdThis field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction.
Example
"threeDSecure":{
    "eci":"05",
    "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version":"2.1.0",
    "flow":"challenge"
    "dsTransactionId":"1231-2342-3453-4564"
    "challengeMandatedIndicator":"Y"
    "authenticationType":"2"
    "acsTransactionId":"7777-8797-4645-1233"
  },

Values returned in the resultDetails object

ValueReturned for brandDescription
CB_Authentication_value_algorithmCartes BancairesIdentifies the algorithm used by the ACS to calculate the Authentication Value. For example: 0 = HMAC (per SET stain); 1 = CVV; 2 = CVV with ATN; 3 = SPA AAC; A = AV-CB
CB_ScoreCartes BancairesGlobal score calculated by the Cartes Bancaires Scoring platform

Example

"resultDetails":{
    "ExtendedDescription":"Approved or completed successfully",
    "clearingInstituteName":"Clearing_Institute",
    "ConnectorTxID1":"12345",
    "AcquirerResponse":"00",
    "reconciliationId":"132499881"
    "CB_Authentication_value_algorithm":"2"
    "CB_Score":"55"
  },

New return codes

Two new return codes have been introduced in the 3DS 2.0 workflow:

  • 300.100.100 – may be returned during the payment authorization. Indicates that the acquirer or the issuer declined the transaction due to SCA was not applied. This is a soft decline, and the appropriate action to take is to re-submit the transaction with 3D Secure, which will result in a challenge flow.
  • 000.400.110 – Authentication successful (fricitionless flow). This may be returned during the authentication (3D Secure) flow, when the issuer authenticates the transaction solely based on the data received in the authentication request without the need for the cardholder to authenticate themselves
  • 000.400.109 – Card is not enrolled for 3D Secure version 2. This code may be returned during the 3DS lookup request (PReq). If the card is not enrolled for 3DS 2.x, and the fallback to 3DS 1.0 is not enabled, then the transactions status will be 000.400.109

 

Parameters for merchants using 3rd party 3DS Server/MPI

If a merchant is using a third-party 3DS Server provider, and the API is used only for processing authorizations, then some additional parameters might be required:

NameParameterDescription
Directory Server transaction IDthreeDSecure.dsTransactionIdTransaction ID assigned by the directory server
3D Secure versionthreeDSecure.versionVersion of 3D (examples: 1.0.2, 2.1.0, 2.2.0 )
3DS Requestor Challenge IndicatorthreeDSecure.challengeIndicatorIndicates whether a challenge is requested for this transaction. For example: a 3DS Requestor may have concerns about the transaction, and request a challenge. Allows 3DS Requestor to request a challenge such as to follow local/regional mandates or other variables. Possible values:
01No preference
02No challenge requested
03Challenge requested: 3D Secure Requestor Preference
04Challenge requested: Mandate
ACS Challenge mandate indicatorthreeDSecure.challengeMandatedIndicatorIndication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable.
Authentication TypethreeDSecure.authTypeThe type of authentication that was requested by the ACS.
01Static
02Dynamic
03OOB
04Decoupled
Exemption flagthreeDSecure.exemptionFlagFlags the transaction as exemption during authorization. Possible values:
01Low value exemption
02TRA exemption
03Trusted beneficiary exemption
04Corporate card payment exemption
Transaction status reasonthreeDSecure.transactionStatusReasonProvides information on why the Transaction Status field has the specified value.
ACS transaction IDthreeDSecure.acsTransactionIdThis field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction.

Exemptions

Exemptions are particular transactions that can be exempted from SCA, and they don’t necessarily need explicit cardholder authentication. In a simpler way: they can be either authorized without previous authentication, or they will go though a frictionless flow during authentication which means the cardholder doesn’t have authenticate themselves with the issuer.

These exemptions are transactions which are:

    • Low value
    • Low risk
    • Between cardholder and merchant, where the cardholder white-listed the merchant as a ‘trusted beneficiary’
    • Made with a corporate card

 

Merchants can request an exemption by marking the transaction with the exemption flag. It is important to know, that in this case:

      • Merchant takes liability for the transaction
      • The issuer has the power to override the exemption request
      • Some acquirers may not allow certain exemptions for their merchants. Merchants should consult with their acquirers to which extent can they use the exemption flags.

 

Exemptions can be requested in 2 ways:

      • By sending the transaction directly to authorization with an exemption flag (no 3D Secure will be executed, and liability will be with the merchant)
      • By sending the transaction for authentication with an exemption flag (3D Secure will be attempted and the issuer will take the liability)

To request an exemption via authorization (1st option above), it is enough to send only the threeDSecure.exemptionFlag field. To request an exemption via authentication (2nd option above), the parameter that has to be sent depends on the 3D Secure version:

      • For versions 2.1+ and 2.2, only the threeDSecure.exemptionFlag parameter needs to be sent
      • For version 2.1, both threeDSecure.challengeIndicator and threeDSecure. exemptionFlag has to be sent. The reason for this, is that 3DS 2.1 authentication doesn’t support exemptions, but the merchant can still flag the transaction to the issuer their preference.

 

Possible values for the threeDSecure.challengeIndicator and threeDSecure.exemptionFlag fields:

    • threeDSecure.challengeIndicator – should be used in the case when the transaction is sent to the issuer for authentication, but a challenge is not requested.
ValueChallenge preferenceDescription
01No preferenceThe merchant has no preference, and fully trust the issuer to ask a challenge from the cardholder.
02No challenge requestedThe merchant prefers that the cardholder is not authenticated by the issuer, and only the frictionless flow applies
03Challenge requested: 3D Secure Requestor PreferenceThe merchant prefers that the cardholder is authenticated by the issuer.
04Challenge requested: MandateThe cardholder authentication is mandated (eg. by regional mandates)
05No challenge requestedTransactional risk analysis is already performed
06No challenge requestedData share only
07No challenge requestedStrong consumer authentication is already performed
08No challenge requestedUtilise whitelist exemption if no challenge required
09Challenge requestedWhitelist prompt requested if challenge required
  • threeDSecure.exemptionFlag – to indicate the type of exemption requested. Used both in the exemption request during authentication and the authorization process.
ValueExemption
01Low value exemption
02TRA exemption
03Trusted beneficiary exemption
04Corporate card payment exemption

Soft declines

If the exemption is requested via authorization, meaning that the 3D Secure call is skipped, the acquirer has the option to reject the exemption request. In this case the acquirer will ‘soft decline’ the transaction, which is indicated with the return code 300.100.100. The correct action to take is to re-send the transaction to 3D Secure authentication and after that to authorization with the authentication result.

The merchant has 2 options handling the soft decline:
1. The gateway can return the soft decline code, and let the merchant handle the workflow as they wish. 2. The gateway can automatically retry the transaction. If the transaction is retried after a soft decline, the 3D Secure authentication will always end up with a challenge flow for the customer.

 

Out of scope transactions

A certain group of transactions is out of scope from Strong Customer Authentication (SCA). This means, that these transactions can be sent to authorization directly and they will not be declined by the acquirer or the issuer with a soft decline. In order for a transaction to qualify as out of scope it is crucial to mark the transaction with the proper flags.

Transaction type How to flag
Mail order or telephone order Set the field transactionCategory to ‘MO’ or ‘TO’
Recurring transactions Set the field recurringType to REPEATED. This only applies for merchant initiated transactions (MIT), eg. subscription agreement between consumer and merchant.
Merchant Initiated Transactions Set the field standingInstruction.source=MIT Acquirer specific parameter set also needs to be sent. Please refer to the individual Integration Sheets of the acquirer connection you are using.

Additional Features

EMV 3D Secure offers some additional features that were not available in earlier versions. These are optional features but offer a better and more flexible way for merchants to authenticate their customers.

 

Non-payment authentication (NPA)

Non-payment authentication (NPA in short) offers the option to authenticate the shopper even when there is no payment transaction happening and in cases when the transaction amount is not known. For example the cardholder wants to store their card for future payments but doesn’t want to buy anything (card tokenization without payment). NPA offers an easy way for merchants to make sure that the cardholder is authenticated before the card is even tokenized.

There are multiple ways to initiate a non-payment authentication.

1. Authentication during registration
2. Standalone NPA

 

Authentication during registration

To perform a 3D Secure authentication before a card is tokenized, the feature should be enabled on the back-end. Please ask your technical support team to enable this functionality

Once it is activated, when the cardholder registers their card details, it will trigger a 3D Secure 2 authentication before the card registration.

Please note: if the transaction is an authorization (PA) where registration is enabled (by sending createRegistration=true), the 3D Secure authentication will be triggered for the payment transaction and not for the registration.

 

NPA for a payment transaction

You might want to perform an NPA without a registration. For example for an account verification transaction (zero-amount authorization). In this case there are no additional settings or parameters are required. Just make sure that 3D Secure 2 is enabled and NPA will be triggered automatically for zero amount PA payment types.

Additionally, NPA can be forced via an additional parameter. Even if the amount is not zero, if the parameter threeDSecure.npa=true is sent, it will trigger a NPA instead of a regular 3D Secure payment authentication with the payment amount. Please be aware that the authenticated amount should always be the same as the payment amount.

Note: if the amount=0.00 is sent, but threeDSecure.amount is greater than zero, then the 3D Secure authentication will use the amount from the threeDSecure.amount field.

 

3RI authentication

Only available in 3DS 2.2

3RI authentication stands for 3DS Requestor Initiated Authentication. This is an authentication method where the cardholder is not present and the transaction is initiated by the merchant. This type of authentication is mainly used to get the status of an already authenticated transaction in case of delayed shipments.

To request a 3RI authentication as a merchant, send the following 2 fields with the request:

threeDSecure.channel=01
customParameters[PriorReference] = ACS Transaction ID of the cardholder initiated authenticated transaction. This value is present in the response of the authenticated transaction, in the acsTransactionId field.

 

Decoupled authentication

Only available in 3DS 2.2

Decoupled Authentication is an authentication method whereby authentication can occur independent from the cardholder’s experience with the 3DS Requestor (merchant). During decoupled authentication the shopper will not do the authentication during the challenge flow in the iframe on the merchant’s website, but separately via a mobile application for example.

To request a decoupled authentication from the issuer, send the threeDSecure.decoupled=true field with the request.

Please be aware that not all issuers support decoupled authentication. In case it’s not supported, the transaction will be authenticated with the normal workflow.

Versions available

Scheme Version
Visa 2.2
Mastercard 2.1+
American Express 2.1
Discover/Diners 2.1
JCB 2.2
Carte Bancaire 2.1