Last Updated: 08 October 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

application/vnd.worldpay.verifications.customers-v3.hal+json

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.cardHolderName
riskData.account.email ¹
riskData.transaction.phoneNumber ¹
transaction.firstName ²
transaction.lastName ²
deviceData.ipAddress

¹ Either customer.email or customer.phoneNumber are required.

² Only required if instruction.paymentInstrument.cardHolderName is not provided

EMVco Recommended values

instruction.paymentInstrument.billingAddress.city
instruction.paymentInstrument.billingAddress.country
instruction.paymentInstrument.billingAddress.address1
instruction.paymentInstrument.billingAddress.postalCode
instruction.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:

For the native SDK the application data is collected as part of initialization. Browser specific device data is not required.

deviceData.ipAddress

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.

transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference for authentication. For example, e-commerce order code. Use the same transactionReference across all 3 potential request types (deviceDataInitialization, authentication, verification).

merchantobjectrequired

An object that contains information about the merchant and API level configuration.

instructionobjectrequired

The object that contains all the payment information related to the authentication request.

deviceDataobjectrequired

Object containing device data information.

challengeobjectrequired

An object that contains challenge related information.

riskDataobject

Object containing additional risk data.

Authentication responses

Best Practice

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

authenticated

{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}

authenticated - Cartes Bancaires

{
    "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"
    }
}

Apply the details (such as eci, version, authenticationValue, transactionId) required by Card Payments in the authorization request. If the outcome is challenged, proceed with challenge display & verification. See Testing for details.

Next steps

Challenge
Take a payment
Testing