Initiate the 3DS authentication

Request

Authenticate your customer by submitting order and risk data.

Security

BasicAuth

Content-Typestring

Example:application/vnd.worldpay.verifications.customers-v2.hal+json

Acceptstring

Example:application/vnd.worldpay.verifications.customers-v2.hal+json

Bodyapplication/vnd.worldpay.verifications.customers-v2.hal+json

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

A unique reference for authentication. For example, e-commerce order code.

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.

{
  "transactionReference": "uniqueId",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/front",
      "cardHolderName": "Card Holder Name",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
        "address1": "Address 1",
        "address2": "Address 2",
        "address3": "Address 3",
        "postalCode": "Postal Code",
        "city": "City",
        "state": "State",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    }
  },
  "challenge": {
    "returnUrl": "https://returnUrl.com"
  },
  "deviceData": {
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)",
    "collectionReference": "reference"
  },
  "riskData": {
    "account": {
      "previousSuspiciousActivity": true,
      "type": "guestUser",
      "history": {
        "createdAt": "2002-11-23",
        "modifiedAt": "2003-10-21",
        "passwordModifiedAt": "2005-02-10",
        "paymentAccountEnrolledAt": "2004-09-02"
      }
    },
    "transaction": {
      "reorder": true,
      "preOrderDate": "2010-08-04",
      "history": {
        "attemptsLastDay": 2,
        "attemptsLastYear": 6,
        "completedLastSixMonths": 7,
        "addCardsLastDay": 5,
        "shippingAddressFirstUsedAt": "2009-02-22"
      },
      "giftCardsPurchase": {
        "totalValue": {
          "currency": "GBP",
          "amount": 10
        },
        "quantity": 4
      }
    },
    "shipping": {
      "nameMatchesAccountName": false,
      "method": "digital",
      "timeFrame": "electronic",
      "email": "customer@website.com"
    }
  }
}

Responses

The authentication has been created

Bodyapplication/vnd.worldpay.verifications.customers-v2.hal+json

One of:

outcomestringrequired

The outcome of the authentication request.

Enum:"challenged""alreadyAuthenticated""notEnrolled""unavailable""authenticationFailed""authenticated""signatureFailed""bypassed"

transactionReferencestring, [ 1 .. 64 ] characters

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

authenticationobject

Object that contains authentication related information.

challengeobject

Object containing challenge related information in case of a "challenged" flow

Response

{
  "outcome": "authenticated",
  "transactionReference": "uniqueId",
  "authentication": {
    "version": "2.1.0",
    "authenticationValue": "authValue",
    "eci": "02",
    "transactionId": "transaction1234567890"
  }
}