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) |
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:
- 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).
- 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.ip | 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:
|
Server to Server response
Server to Server response - intermediate
{ "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.oppwa.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": "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" }
Server to Server response - final
{ "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" }
-
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>
-
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 | Required unless market or regional mandate restricts sending this information. | Cardholder (via widget or API) | Cardholder (via API) |
billing.country | Required unless market or regional mandate restricts sending this information. | Cardholder (via widget or API) | Cardholder (via API) |
billing.street1 | Required unless market or regional mandate restricts sending this information. | Cardholder (via widget or API) | Cardholder (via API) |
billing.postcode | Required unless market or regional mandate restricts sending this information. | Cardholder (via widget or API) | Cardholder (via API) |
customer.email | Required unless market or regional mandate restricts sending this information. | Cardholder (via widget or API) | Cardholder (via API) |
card.holder | Required unless 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.ip | Optional | Automatically collected by the widget | Merchant should collect and send via API |
customer.browser.javaEnabled | Mandatory | 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.challengeIndicator 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.challengeIndicator 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:
|
||||||||||||||
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:
|
||||||||||||||
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[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:
|
||||||||||||||
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:
|
||||||||||||||
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:
|
||||||||||||||
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:
|
||||||||||||||
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:
|
||||||||||||||
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:
|
||||||||||||||
customParameters[ShipNameIndicator] |
Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. Possible values are:
|
||||||||||||||
customParameters[SuspiciousAccountActivity] |
Indicates whether the 3D Secure Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. Possible values are:
|
||||||||||||||
customParameters[TransactionType] |
Identifies the type of transaction being authenticated. Possible values are:
|
||||||||||||||
customParameters[DeliveryTimeframe] |
Indicates the merchandise delivery timeframe. Possible values are:
|
||||||||||||||
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:
|
||||||||||||||
customParameters[PreOrderPurchaseIndicator] |
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. Possible values are:
|
||||||||||||||
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
Value | Description |
---|---|
eci | Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. |
verificationId | Payment 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. |
version | Version of the 3D Secure that was used for authentication |
flow | Indicates the user flow that was applied during the authentication: challenge or frictionless |
dsTransactionId | Universally unique transaction identifier assigned by the DS to identify a single transaction. |
challengeMandatedIndicator | Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable. |
authenticationType | Authentication approach that the ACS used to authenticate the Cardholder for this specific transaction. |
Example
"threeDSecure":{ "eci":"05", "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=", "version":"2.1.0", "flow":"challenge" "dsTransactionId":"1231-2342-3453-4564" "challengeMandatedIndicator":"Y" "authenticationType":"2" },
Values returned in the resultDetails object
Value | Returned for brand | Description |
---|---|---|
CB_Authentication_value_algorithm | Cartes Bancaires | Identifies 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_Score | Cartes Bancaires | Global 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
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:
Name | Parameter | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
Directory Server transaction ID | threeDSecure.dsTransactionId | Transaction ID assigned by the directory server | ||||||||
3D Secure version | threeDSecure.version | Version of 3D (examples: 1.0.2, 2.1.0, 2.2.0 ) | ||||||||
3DS Requestor Challenge Indicator | threeDSecure.challengeIndicator | Indicates 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:
|
||||||||
ACS Challenge mandate indicator | threeDSecure.challengeMandatedIndicator | Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable. | ||||||||
Authentication Type | threeDSecure.authenticationType | The type of authentication that was requested by the ACS.
|
||||||||
Exemption flag | threeDSecure.exemptionFlag | Flags the transaction as exemption during authorization. Possible values:
|
||||||||
Transaction status reason | threeDSecure.transactionStatusReason | Provides information on why the Transaction Status field has the specified value. |
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.
There are 2 fields defined which should be used in a combination to request an exemption:
- threeDSecure.challengeIndicator - should be used in the case when the transaction is sent to the issuer for authentication, but a challenge is not requested.
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)
Value | Exemption |
---|---|
01 | Low value exemption |
02 | TRA exemption |
03 | Trusted beneficiary exemption |
04 | Corporate card payment exemption |
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 (note: this field is not available at the moment) Acquirer specific parameter set also needs to be sent. Please refer to the individual Integration Sheets of the acquirer connection you are using. |