Skip to content
APIs/3DS/3DS Authentication

3DS Authentication

3DS authentication request.

Merchant facing API.

Operations

Authentication

Request

Authenticate your customer by submitting order and risk data.

Security
BasicAuth
Headers
WP-Api-Versionstringrequired

The API version.

Value:"2026-10-01"
Example:2026-10-01
Bodyapplication/json
orderReferencestring, [ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

Merchant specific reference for the order (e.g. generated ecommerce system order number). Does not have to be unique as multiple payments may apply to a single order.

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

A unique reference per authentication request provided by you that is used to identify the authentication throughout its lifecycle.

Example:"request-5678"
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.

customerobject
challengeobject

An object that contains challenge related information.

previousSuspiciousActivityboolean

Has the account been flagged for suspicious activity.

userTypestring
Enum:"guestUser""registeredUser""federatedAccount""issuerCredentials""thirdPartyAuthentication""fidoAuthenticator"
accountHistoryobject

Customer account history.

Example:
{
  "createdAt": "2019-11-18",
  "modifiedAt": "2020-05-12",
  "passwordModifiedAt": "2021-03-15",
  "paymentAccountEnrolledAt": "2021-06-20"
}
reorderboolean

Repeat of a previous order.

preOrderDatestring, (date)

Expected date that a pre-ordered purchase will be available. Provide in ISO 8601 format.

Example:"2021-12-25"
transactionHistoryobject

Object containing details of the last transaction.

giftCardsPurchaseobject

If the order is being used to purchase a gift card.

shippingobject

Card authentication request with minimum recommended values

{
  "orderReference": "order-1234",
  "transactionReference": "request-5678",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "value": {
      "amount": 100,
      "currency": "GBP"
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardHolderName": "Sherlock Holmes",
      "expiryDate": {
        "month": 1,
        "year": 2028
      },
      "billingAddress": {
        "address1": "221B Baker Street",
        "city": "London",
        "postalCode": "NW1 6XE",
        "countryCode": "GB"
      }
    }
  },
  "deviceData": {
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
  },
  "customer": {
    "firstName": "Sherlock",
    "lastName": "Holmes",
    "phone": "02031234321",
    "email": "sherlock.holmes@example.com"
  }
}

Responses

The authentication has been created.

Bodyapplication/json
outcomestring

Client-side 3DS interaction is required. Load the redirect URL to run device data collection and, if the issuer requires it, a challenge.

Value:"3dsRedirect"
authenticationIdstring

Unique identifier for a single 3ds authentication, generated by Worldpay

Example:"3dsLfC-vuhv7J2nEw2m9ca_e0"
redirectstring

Worldpay hosted URL that runs the client-side 3DS interactions with the card issuer: device data collection (DDC) and, if the issuer requires it, the challenge.

The outcome is sent to your page by postMessage from the Worldpay origin. When the client-side flow is complete, use the query request with the authenticationId to retrieve the authentication result.

Response

Use a hosted 3DS page to wrap and perform device data collection, and when prompted display a challenge from the issuer

{
  "outcome": "3dsRedirect",
  "authenticationId": "3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "redirect": "https://hpp-test.worldpay.com/all/hosted-threeds/3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/3ds/authentications/3dsLfC-Tuhv7J2nEw2m9ca_e0"
    },
    "queryAuthentication": {
      "href": "https://try.access.worldpay.com/3ds/authentications/3dsLfC-Tuhv7J2nEw2m9ca_e0"
    }
  }
}