Last Updated: 17 July 2024 | Change Log
Authentication
POST your authentication request to the 3ds:authenticate action link. Your authentication request sends order and risk data used to decide if a challenge is required.
Authentication example request
An example of a 3DS2 Authentication request containing card details which results in an authenticated response
{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "default", "overrideName": "The Baskerville Animal Sanctuary", "acquirerId": "01234567" }, "instruction": { "paymentInstrument": { "type": "card/front", "cardHolderName": "Sherlock Holmes", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 5, "year": 2035 }, "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "countryCode": "GB" } }, "value": { "currency": "GBP", "amount": 250 } }, "deviceData": { "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5", "acceptHeader": "text/html", "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)", "browserLanguage": "en-GB", "browserJavaEnabled": "true", "browserColorDepth": "15", "browserScreenHeight": "1200", "browserScreenWidth": "900", "timeZone": "-300", "browserJavascriptEnabled": "true", "ipAddress": "192.0.0.0" }, "challenge": { "windowSize": "600x400", "preference": "noPreference", "returnUrl": "http://payment.example.com" }, "riskData": { "account": { "previousSuspiciousActivity": false, "type": "registeredUser", "email": "sherlock.holmes@example.com", "history": { "createdAt": "2019-11-18", "modifiedAt": "2019-11-18", "passwordModifiedAt": "2019-10-15", "paymentAccountEnrolledAt": "2019-11-18" } }, "transaction": { "reorder": true, "preOrderDate": "2019-11-18", "firstName": "Sherlock", "lastName": "Holmes", "phoneNumber": "00000000000", "history": { "attemptsLastDay": 2, "attemptsLastYear": 6, "completedLastSixMonths": 6, "addCardsLastDay": 5, "shippingAddressFirstUsedAt": "2018-09-18" }, "giftCardsPurchase": { "totalValue": { "currency": "GBP", "amount": 10 }, "quantity": 4 } }, "shipping": { "nameMatchesAccountName": false, "method": "verifiedAddress", "timeFrame": "nextDay", "email": "sherlock.holmes@example.com", "address": { "address1": "Disneyland", "address2": "Disneyland Drive", "address3": "Adventure Park", "postalCode": "DL1 2CA", "city": "Anaheim", "stateCode": "CA", "countryCode": "GB", "phoneNumber": "01911234321" } } } }
How much data to provide
The device data and values in the authentication request are used by the issuer to decide if the transaction is likely to be fraudulent.
How this data is interpreted varies by issuer. Supplying more data increases the chances of the outcome being frictionless (without a challenge).
Some issuers may fail the authentication entirely without the recommended fields.
EMVco required values
instruction.paymentInstrument.cardHolderNameriskData.account.email1riskData.transaction.phoneNumber1transaction.firstNametransaction.lastNamedeviceData.browserLanguage2deviceData.ipAddressdeviceData.browserScreenWidth2deviceData.browserScreenHeight2
1 Either customer.email or customer.phoneNumber are required.
2 Provide for web/browser integration only
EMVco Recommended values
instruction.paymentInstrument.billingAddress.cityinstruction.paymentInstrument.billingAddress.countryinstruction.paymentInstrument.billingAddress.address1instruction.paymentInstrument.billingAddress.postalCodeinstruction.paymentInstrument.billingAddress.state
Device Data Collection Failure
In the event the device data collection fails to run (browser/native), additionally provide the following, to maintain healthy authentication rates and reduce issuer challenges:
deviceData.ipAddress1deviceData.browserLanguagedeviceData.browserScreenHeightdeviceData.browserScreenWidthdeviceData.browserJavaEnableddeviceData.browserColorDepthdeviceData.timeZonedeviceData.browserJavascriptEnabled
1 Only this value applies to (iOS/Android), the others are not applicable
Full authentication request schema
You can either see the full schema in the API Reference section or expand the sections below. The riskData object in particular contains additional data that, while not mandatory or specifically recommended by EMVco, may be used by some issuers as part of their risk analysis.
A unique reference for authentication. For example, e-commerce order code. Use the same transactionReference across all 3 potential request types (deviceDataInitialization, authentication, verification).
An object that contains information about the merchant and API level configuration.
The object that contains all the payment information related to the authentication request.
Object containing device data information.
An object that contains challenge related information.
Object containing additional risk data.
Authentication responses
Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.
The response contains the outcome of your authentication request. To understand more about the outcomes and how to reproduce them, see 3DS testing.
You can see the full response schema in the API Reference.
Successful frictionless authentication
{ "outcome": "authenticated", "transactionReference": "Memory265-13/08/1876", "authentication": { "version": "2.1.0", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=", "eci": "05", "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645" } }
{ "outcome": "authenticated", "transactionReference": "Memory265-13/08/1876", "authentication": { "version": "2.1.0", "authenticationValue": "AJkBBkhgQQAAAE4gSEJydQAAAAA=", "eci": "05", "transactionId": "be122acf-0ba7-4eff-aa5b-fb53e9ad2f87", "cryptogramAlgorithm": 1, "challengePreference": "challengeMandated", "authenticationFlow": "frictionless", "brand": "cartesBancaires", "acsTransactionId": "c7f708b7-50fc-422e-be62-e9601703b48e" } }
Next steps