Skip to content
APIs/3DS/
/
Authentication

Authentication

Request

Authenticate your customer by submitting order and risk data.

Security
BasicAuth
Headers
WP-Api-Versionstringrequired

The API version.

Value:"2026-12-01"
Example:2026-12-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

Redirect.

Value:"3dsRedirect"
authenticationIdstring

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

Example:"3dsLfC-vuhv7J2nEw2m9ca_e0"
redirectstring

The URL to redirect your customer to.

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-bsh.securedataplatform.co.uk/all/hosted-threeds/3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.co.uk/3ds/authentications/{authenticationId}"
    }
  }
}