We have released a new version. Documentation for our latest version can be found here.

Last Updated: 17 January 2024 | Change Log


POST your authentication request to the 3ds:authenticate action link. Your authentication request sends order and risk data used to decide if a challenge is required.

Authentication example request


Authentication request body:

  1. Card
  2. Token
  3. Network Payment Token
  "transactionReference": "unique-transactionReference",
  "merchant": {
    "entity": "default"
  "instruction": {
    "paymentInstrument": {
      "type": "card/front",
      "cardHolderName": "John Appleseed",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      "billingAddress": {
        "address1": "Worldpay",
        "address2": "1 Milton Road",
        "address3": "The Science Park",
        "postalCode": "CB4 0WE",
        "city": "Cambridge",
        "countryCode": "GB"
    "value": {
      "currency": "GBP",
      "amount": 250
  "deviceData": {
    "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
  "challenge": {
    "returnUrl": ""
transactionReferenceA unique reference for authentication. for example, e-commerce order code.
merchant.entityUsed to route the authentication request in Access Worldpay, created as part of on-boarding.
instructionThe object that contains all the payment information related to the authentication request.
instruction.paymentInstrumentAn object that contains the card details or token location.
paymentInstrument.typeAn identifier for the paymentInstrument being used.

type : card/front type : card/tokenized
paymentInstrument.billingAddressAn object containing the billing address information. If included you must send at least:
  • State - should only be provided following the ISO-3611-2 two-character sub division e.g.“CA” for California). We recommend you provide this for US addresses
deviceData.acceptHeaderUsed by the issuer to check if the customer's browser is compatible with the issuer challenge display.
deviceData.userAgentHeaderUsed by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321
E.g. Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)
If no value is provided the authentication falls back to 3DS1.
deviceData.browserLanguageYour 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
deviceData.ipAddressA unique identifier for your customer's physical location that can be used by the issuer in risk analysis. Must be in IPv4 format. E.g.
challenge.windowSizeSpecify the challenge window size (width x height) that the issuer should use. This is to better tailor the experience to the customers device.
  • 250x400
  • 390x400 (default)
  • 600x400
  • 500x600
  • fullpage - expand to fill viewport
The 3DS1 specification default is 390x400 but we recommend a minimum of 400x500 as not all issuers conform strictly
  • noPreference - default
  • noChallengeRequested - prefer no challenge performed
  • challengeRequested - prefer challenge is performed
  • challengeMandated - local or region mandates meaning a challenge must be performed
  • You must use challengeMandated when first storing cards in general (e.g. first payment where a token is stored or independently "adding a card" to an account).
  • You should use challengeMandated in the authentication request as part of the first CIT payment in an MIT series or when using the Checkout SDK to take payments.
  • The interpretation of this field varies from issuer to issuer, so Worldpay cannot guarantee any particular behavior on their part as a result of you setting this field.
challenge.returnUrlOnce the customer completes the challenge page the issuer will redirect/post to the returnUrl in order for you to resume the session. It must be the full URL path.

The issuer prioritizes device data collection values for risk analysis over the browser language and IP address details. We recommend you still include these details. In case of unsuccessful device data collection, the authentication may fail if you do not include them.

Optional fields in an Authentication request

Optional fields

Markdown content here.

Complete Authentication request schema

Full Authentication request body:

  1. Card
  2. Token
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "MindPalaceLtd"
  "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
  "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",
    "ipAddress": ""
  "challenge": {
    "windowSize": "600x400",
    "preference": "noPreference",
    "returnUrl": ""
  "riskData": {
    "account": {
      "previousSuspiciousActivity": false,
      "type": "registeredUser",
      "email": "",
      "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": "",
      "address": {
        "address1": "Disneyland",
        "address2": "Disneyland Drive",
        "address3": "Adventure Park",
        "postalCode": "DL1 2CA",
        "city": "Anaheim",
        "stateCode": "CA",
        "countryCode": "GB",
        "phoneNumber": "01911234321"

Risk data

To reduce the chance of a challenged outcome we recommend that you include additional riskData in your authentication request.

The additional riskData is used by your customer's card issuer. It decides if your authentication request requires a challenge or can be authenticated successfully without a challenge (also known as frictionless authentication).


Recommended values for a frictionless authentication are marked in the tables below and may become mandatory in future versions of the API.

There are three riskData objects you can include in your request:


Descriptions of your additional Account riskData parameters:

accountObject containing all customer account related risk data.
  • true
  • false
  • guestUser - Order placed without full merchant account registration (no password)
  • registeredUser- Order placed with full merchant account registration (password entered)
  • federatedAccount - Using a Federated ID
  • issuerCredentials- Using issuer credentials
  • thirdPartyAuthentication - Using third party authentication
  • fidoAuthenticator - FIDO authentication standard
The customer's email address.
account.history.createdAtWhen the account was created.
account.history.modifiedAtWhen the account was last modified.
account.history.passwordModifiedAtWhen the account password was last changed.
account.history.paymentAccountEnrolledAtDate the payment account was added to the cardholder account.

Descriptions of your additional Transaction riskData parameters:

transactionObject containing all customer transaction related risk data.
transaction.reorderRepeat of a previous order :
  • true
  • false
transaction.preOrderDateExpected date that a pre-ordered purchase will be available.
Customer's first name.
Customer's last name.
transaction.phoneNumberCustomer's phone number.
transaction.historyObject containing details of the last transaction.
history.attemptsLastDayNumber of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
history.attemptsLastYearNumber of transactions (successful or abandoned) for this cardholder account within the last year.
history.completedLastSixMonthsNumber of purchases with this cardholder account during the previous six months.
history.addCardsLastDayNumber of attempts to add a card in the last 24hrs.
history.shippingAddressFirstUsedAtWhen the shipping address used for the transaction was first used.
transaction.giftCardsPurchaseIf the order is being used to purchase a gift card.
giftCardsPurchase.totalValue.currencyThe 3 digit currency code. See list of supported currencies. If provided must include totalValue.amount.
giftCardsPurchase.totalValue.amountThe amount being placed on the gift card. If provided must include totalValue.currency.
giftCardsPurchase.quantityThe number of gift cards being purchased.

Descriptions of your additional Shipping riskData parameters:

shippingObject containing all data related to how the order will be shipped.
shipping.nameMatchesAccountNameCardholder name on account is identical to the shipping name:
  • true
  • false
  • billingAddress - Ship to customers 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
  • electronic
  • sameDay
  • nextDay
  • twoDaysPlus
shipping.emailThe email address used for an electronic delivery.
shipping.addressAn object containing the shippping address information. If included, you must send at least:

Authentication responses

The response contains the outcome of your authentication request.

  1. Authenticated
  2. Authenticated Cartes Bancaire
  3. Authentication Failed
  4. Authentication Failed Cartes Bancaires
  5. Challenged
  6. Not Enrolled
  7. Unavailable
  8. Bypassed
    "outcome": "authenticated",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
outcomeThe outcome of your authentication request.
  • authenticated - Successful frictionless authentication.
  • authenticationFailed - Your customer could not be authenticated successfully.
  • challenged - Authentication details should not be trusted. Challenge required.
  • notEnrolled - Issuer not enrolled for 3DS.
  • unavailable - Authentication unavailable.
  • bypassed - 3DS check is bypassed. Returned if 3DS premium is enabled or when there is a timeout connecting to the 3DS directory server.
To understand more about the outcomes and how to reproduce them, see 3DS testing.
challenge.reference This links the authentication response to the subsequent challenge form and verification request.
challenge.urlPOST action on the challenge form. Used to redirect to the issuers challenge page as part of the challenge form.
Do not use the challengeUrl as the source(src) in the iframe.
challenge.jwtA digitally signed token that contains additional details, such as the URL to return to after the challenge screen.
Expires in 10 minutes for both Try and Production.
challenge.payloadJSON container with extra data required for the challenge.
This is only for use with the native mobile App SDK's. It is not required for the web integration.
authentication.versionThe version of 3DS used to process the transaction.
Required for Mastercard's Identity Check transactions in Authorization.
authentication.authenticationValueA cryptographic value that provides evidence of the outcome of a 3DS verification.
  • Visa - Cardholder Authentication Verification Value (CAVV)
  • Mastercard - Universal Cardholder Authentication Field (UCAF)

Used when authorizing a payment.
authentication.eciElectronic Commerce Indicator (ECI).
Indicates the outcome of the 3DS authentication.
  • 02 or 05 - Fully Authenticated Transaction
  • 01 or 06 - Attempted Authentication Transaction
  • 00 or 07 - Non 3-D Secure Transaction
  • Mastercard - 02, 01, 00
  • Visa - 05, 06, 07
  • Amex - 05, 06, 07
  • JCB - 05, 06, 07
  • Diners - 05, 06, 07

You will need to use this when you are authorizing a payment.
authentication.transactionIdA transaction identifier.
If provided, you should use it as part of your payment authorization.
If the authentication.version has a major version of:
  • 1 - value returned known as xid
  • 2 - value returned known as dsTransactionId
authentication.cryptogramAlgorithmIndicates the algorithm used to generate the cryptogram. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.
authentication.challengePreferenceIndicates the preferred challenge behavior. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.
  • noPrefrence
  • noChallengeRequested
  • challengeRequested
  • challengeMandated
  • challenge - Your customer was redirected to their bank to complete authentication
  • frictionless - Your customer completed authentication without needing to be redirected to their bank

Returned for Cartes Bancaires authentications only and must be applied in the following authorization.
authentication.statusReasonProvides further information relating to the outcome of the authentication. Returned for failed authentications only. Returned for Cartes Bancaires authentications only.
authentication.cancellationIndicatorAn 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 & 05 - Authentication timed out at ACS provider
  • - 06 - Transaction error
  • - 07 - Unknown
  • - 08 - Transaction timed out at SDK
authentication.networkScoreThe global score calculated by the Cartes Bancaires scoring platform. Returned for Cartes Bancaires authentications only.
authentication.brandThe card brand used in the authentication. Returned for Cartes Bancaires authentications only and must be applied in the following authorization.

In case of an error, you can get further information in our error reference.

Next steps

Take a payment
3DS testing