Skip to content
APIs/3DS/
Initiate the 3DS authenti...

Initiate the 3DS authentication

Request

Authenticate your customer by submitting order and risk data.

Security
BasicAuth
Headers
Content-Typestring
Example:application/vnd.worldpay.verifications.customers-v3.hal+json
Acceptstring
Example:application/vnd.worldpay.verifications.customers-v3.hal+json
Bodyapplication/vnd.worldpay.verifications.customers-v3.hal+json
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.

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": "Baskerville 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
    },
    "routing": {
      "preferredCardBrand": "visa"
    }
  },
  "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"
      }
    }
  }
}

Responses

The authentication has been created

Bodyapplication/vnd.worldpay.verifications.customers-v3.hal+json
Any of:
outcomestringrequired

The outcome of the authentication request.

Enum:"alreadyAuthenticated""authenticated""authenticationFailed""authenticationOutage""bypassed""challenged""notEnrolled""signatureFailed""unavailable"
transactionReferencestring, [ 1 .. 64 ] characters

A unique reference for authentication that was passed in the request.

acsTransactionIdstring, [ 1 .. 36 ] characters

An identifier assigned by the Access Control Server (ACS) to identify a single transaction. Used primarily for Mastercard 3RI subsequent transactions to link the subsequent transaction back to a previous cardholder authentication. Can be disregarded unless otherwise needed.

statusstring, [ 1 .. 2 ] characters

Indicates the outcome of the authentication or verification request.

  • Y - Successful authentication
  • N - Failed authentication
  • U - Unable to complete authentication
  • A - Successful attempts authentication
  • C - Challenged authentication
  • R - Authentication rejected (merchant must not submit for authorization)
  • I - Exemption acknowledged
enrolledstring, = 1 characters

Status of authentication eligibility.

  • Y - Bank is participating in 3DS
  • N - Bank is not participating in 3DS
  • U - The Directory Server (DS) or Access Control Server (ACS) were not available at the time of the request
  • B - Merchant authentication rule is triggered to bypass authentication (3DS premium only)
authenticationobject

Object that contains authentication related information.

Response

Successful frictionless authentication

{
  "outcome": "authenticated",
  "transactionReference": "Memory265-13/08/1876",
  "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
  "status": "Y",
  "enrolled": "Y",
  "authentication": {
    "version": "2.1.0",
    "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "eci": "05",
    "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
  }
}