Skip to content
APIs/3DS/3DS Authentication

3DS (2026-12-01)

Preview only

This is a preview of the next major version and is subject to change.

Estimated availability: Late 2026

Verify your customer's identity to minimize fraud. Use our Strong Customer Authentication (SCA) to benefit from liability shift.

Authentication

Set your headers

Authorization: {your_credentials} 
Content-Type: application/json  
WP-Api-Version: 2026-12-01

Replace {your_credentials} with your base64-encoded Basic Auth username and password.

DNS whitelisting

Whitelist the following URLs:

  • https://try.access.worldpay.com/
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Test (Try)
https://try.access.worldpay.com/3ds
Live
https://access.worldpay.com/3ds

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-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_!@#$%()*=.:;?\[\]{}~`/+]*$

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.

entitystring[ 1 .. 64 ] characters^[A-Za-z0-9 ]*$required

We use this to route your request. We create the entity as part of on-boarding.

Example: "default"
overrideNamestring

Used to override the merchant name that's both submitted to issuers as well as displayed to the customer in the authentication process. PayFac merchants should submit the name of their submerchant.

acquirerIdstring[ 1 .. 20 ] characters^[0-9]*$

Instructs the issuer that the following authorization will be completed with an external acquirer.

Example: "01234567"
instructionobjectrequired

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

valueobjectrequired

An object that contains information about the value of the authentication.

paymentInstrumentanyrequired

An object that contains the card details or token location.

deviceDataobject

Object containing device data information.

acceptHeaderstring[ 1 .. 2048 ] characters

Used by the issuer to check if the customer's browser is compatible with the issuer challenge display.

userAgentHeaderstring[ 1 .. 2048 ] characters

Used by issuers as part of risk analysis and to correctly display the challenge. Must conform to RFC 7321 e.g. Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0).

browserLanguagestring[ 1 .. 8 ] characters

Your customer's browser language that can be used by the issuer in risk analysis. Must conform to the language tags defined by IETF, e.g. en-GB, fr-FR.

ipAddressstring

A unique identifier for your customer's physical location that can be used by the issuer in risk analysis. Must be in IPv4 or IPv6 format, e.g. 192.0.0.0.

browserJavaEnabledboolean

Defines whether Java is enabled on your customer's browser.

browserColorDepthstring

The color depth of your customer's browser.

Enum"1""4""8""15""16""24""32""48"
browserScreenHeightinteger(int32)

Defines the pixel height of the customer's browser.

browserScreenWidthinteger(int32)

Defines the pixel width of the customer's browser.

timeZonestring^[+-]?\d{1,4}$

Time zone offset in minutes between UTC and your customer's browser local time.
Example time zone offset values in minutes:
If UTC -5 hours:
300
+300
If UTC +5 hours:
-300

browserJavascriptEnabledboolean

Defines whether Javascript is enabled on your customer's browser.

customerobject
firstNamestring[ 1 .. 22 ] characters

Customer's first name.

lastNamestring[ 1 .. 22 ] characters

Customer's last name.

phonestring[ 4 .. 20 ] characters^[0-9]*$

Customer's phone number.

emailstring[ 1 .. 128 ] characters

Customer's email address used for the ecommerce account.

challengeobject

An object that contains challenge related information.

preferencestring

Preference regarding issuer displaying challenge to the customer. The interpretation of this field varies from issuer to issuer, so we cannot guarantee any particular behavior on their part as a result of you setting this field.

Enum ValueDescription
noPreference

Default (decision to challenge owned by issuer).

noChallengeRequested

Prefer no challenge performed.

challengeRequested

Prefer challenge is performed.

challengeMandated

Local or regional mandates meaning a challenge must be performed. For SCA mandated countries you should use challengeMandated in the authentication request as part of the first CIT payment in an MIT series.

noChallengeRequestedTRAPerformed

Prefer no challenge performed due to an exemption to SCA. Only use this when Transaction Risk Analysis (TRA) has been performed using an approved third party vendor and an SCA exemption has been recommended for the authentication.

windowSizestring

Specify the challenge window size (width x height) that the issuer should use.

Default "390x400"
Enum"390x400""250x400""500x600""600x400""fullPage"
previousSuspiciousActivityboolean

Has the account been flagged for suspicious activity.

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

Customer account history.

createdAtstring

Date the customer account was created.

modifiedAtstring

Date the customer account was last modified.

passwordModifiedAtstring

Date the password for the customer account was last modified.

paymentAccountEnrolledAtstring

Date the payment account was added to the cardholder account.

reorderboolean

Repeat of a previous order.

preOrderDatestring

Expected date that a pre-ordered purchase will be available.

transactionHistoryobject

Object containing details of the last transaction.

attemptsLastDayinteger(int32)

Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.

attemptsLastYearinteger(int32)

Number of transactions (successful or abandoned) for this cardholder account within the last year.

completedLastSixMonthsinteger(int32)

Number of purchases with this customer account during the previous six months.

addCardsLastDayinteger(int32)

Number of attempts to add a card in the last 24hrs.

shippingAddressFirstUsedAtstring

When the shipping address used for the transaction was first used.

giftCardsPurchaseobject

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

totalValueobject

An object that contains information about the value of the authentication.

quantityinteger(int32)

The number of gift cards being purchased.

shippingobject
nameMatchesAccountNameboolean

If customer name on account is identical to the shipping name.

methodstring

The shipping method used.

Enum ValueDescription
billingAddress

Ship to customer's billing address.

verifiedAddress

Ship to another verified address on file with merchant.

otherAddress

Ship to address that is different than billing address.

store

Ship to store (store address should be populated on request).

digital

Digital goods.

unshippedTickets

Travel and event tickets, not shipped.

other

Other.

timeFramestring
Enum"electronic""sameDay""nextDay""twoDaysPlus"
emailstring[ 1 .. 128 ] characters

The email address used for an electronic delivery.

phonestring[ 4 .. 20 ] characters^[0-9]*$

The phone number used for delivery.

firstNamestring[ 1 .. 22 ] characters

First name used on the shipping address.

lastNamestring[ 1 .. 22 ] characters

Last name used on the shipping address.

addressobject
application/json
{
  "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"
      }
    }
  },
  "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 generated by us.

  • 25 characters total
  • 3 char prefix 3ds
  • 21 nanoid
  • 1 char suffix - currently always 0 (reserved for global traffic routing as part of a future state of Worldpay.)
Example: "3dsLfC-vuhv7J2nEw2m9ca_e0"
redirectstring

The URL to redirect your customer to.

_linksobject
selfobject
Response
application/json
{
  "outcome": "3dsRedirect",
  "authenticationId": "3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "redirect": "https://hosted.worldpay.com/xxxxxxxxxx/redirect",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/api/3ds/{authenticationId}"
    }
  }
}

Query

Request

Query for the latest authentication state.

Security
BasicAuth
Path
authenticationIdstringrequired

Unique identifier for a single 3ds authentication. Generated by us.

Headers
WP-Api-Versionstringrequired

The API version.

Value"2026-12-01"
Example: 2026-12-01
No request payload

Responses

The authentication has been created

Bodyapplication/json
outcomestringrequired

The latest outcome state for a given request authenticationId.

Enum ValueDescription
3dsAuthenticated

Cardholder successfully authenticated by card issuer.

3dsAttempted

3DS attempted but card issuer not participating. Stand-in authentication.

3dsRejected

Issuer rejects the authentication, do not proceed with payment.

3dsNotAuthenticated

Authentication failure by card issuer (system issue).

3dsUnavailable

Authentication unavailable at this current time.

3dsChallengeFailed

Failed cardholder challenge.

3dsOutage

Issuer recognized outage. Can attempt authentication outage exemption.

3dsBypassed

3DS bypassed based on rules or recommendation from authentication optimization service.

3dsDataOnly

Successful data only authentication.

3dsExempted

Successful exemption in 3DS authentication.

Discriminator
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)
versionstring[ 1 .. 10 ] characters

The version of 3DS used to process the transaction.

authenticationValuestring[ 1 .. 64 ] characters

A cryptographic value that provides evidence of the outcome of a 3DS verification.

  • Visa - Cardholder Authentication Verification Value (CAVV)
  • Mastercard - Universal Cardholder Authentication Field (UCAF)
ecistring[ 1 .. 2 ] characters

Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication.

ECIMeaning
02 or 05Fully Authenticated Transaction
01 or 06Attempted Authentication Transaction
00 or 07Non 3-D Secure Transaction
SchemeValue
Mastercard02, 01, 00
Visa05, 06, 07
Amex05, 06, 07
JCB05, 06, 07
Diners05, 06, 07
dsTransactionIdstring[ 1 .. 64 ] characters

Directory server transaction ID, if provided should be used in the payment authorization authentication object.

acsTransactionIdstring[ 1 .. 64 ] characters

ACS transaction ID, if provided should be used in the payment authorization authentication object.

cryptogramAlgorithmstring[ 1 .. 99999 ] characters

Indicates the algorithm used to generate the cryptogram. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

challengePreferencestring[ 1 .. 64 ] characters

Indicates the preferred challenge behavior. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

  • noPreference
  • noChallengeRequested
  • challengeRequested
  • challengeMandated
authenticationFlowstring[ 1 .. 64 ] characters

Indicates which flow the customer has been directed to. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

Enum"challenge""frictionless"
statusReasonstring[ 1 .. 2 ] characters

Provides further information relating to the outcome of the authentication. Returned for failed authentications only. Returned for Cartes Bancaires authentications only.

cancellationIndicatorstring[ 0 .. 2 ] characters

An indicator as to why the authentication was cancelled. Returned for Cartes Bancaires authentications only.

  • 01 - Cardholder selected cancel
  • 02 - Reserved for future use
  • 03 - Authentication timed out
  • 04 and 05 - Authentication timed out at ACS provider
  • 06 - Transaction error
  • 07 - Unknown
  • 08 - Transaction timed out at SDK
networkScorestring[ 0 .. 2 ] characters

The global score calculated by the Cartes Bancaires scoring platform. Returned for Cartes Bancaires authentications only.

brandstring[ 0 .. 64 ] characters

The card brand used in the authentication. Returned for Cartes Bancaires authentications only and must be applied in the following authorization.

_linksobject
selfobject
Response
application/json
{
  "outcome": "3dsAuthenticated",
  "status": "Y",
  "enrolled": "Y",
  "version": "2.2.0",
  "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
  "eci": "05",
  "dsTransactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645",
  "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/api/3ds/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}