Last updated: 19 May 2026 | Change log

Use Integrated 3DS when you want Worldpay to orchestrate 3DS authentication as part of the payment flow.

With Integrated 3DS, Payments API handles the authentication orchestration and returns the actions you need to continue the payment. Depending on the issuer's decision, the customer may complete a frictionless authentication or be asked to complete a challenge.

At a high level, the Integrated 3DS payment flow works as follows:

1. Add the threeDS object to the payments request to enable 3DS.
2. A response outcome of 3dsDeviceDataRequired will provide details to perform the issuer's Device Data Collection on the customer's browser.
3. Resume the payment using the supply3dsDeviceData action from the response. If frictionless the payment will proceed and authorize.
4. If the outcome is 3dsChallenged details will be provided to display the issuer's challenge page.
5. Resume the payment using the complete3dsChallenge action from the response to proceed with the payment.

To enable Integrated 3DS, include threeDS.type: "integrated" in the payment request.

{
  "instruction": {
    ...
    "threeDS": {
      "type": "integrated",
      "mode": "always",
      "challenge": {
        "returnUrl": "https://payment.example.com/3ds/return"
      },
      "deviceData": {
        "acceptHeader": "text/html",
        "userAgentHeader": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "browserLanguage": "en-GB",
        "browserScreenHeight": 1200,
        "browserScreenWidth": 900,
        "browserJavaEnabled": true,
        "browserColorDepth": "32",
        "timeZone": "300",
        "browserJavascriptEnabled": true,
        "channel": "browser"
      }
    }
  }
}

The Integrated 3DS flow depends on your client environment. Choose the guide that matches your checkout experience.

When Payments API returns 3dsDeviceDataRequired, the response includes the information required to perform Device Data Collection.

The response also includes a supply3dsDeviceData action. Use this action to resume the payment after Device Data Collection has completed.

{
  "outcome": "3dsDeviceDataRequired",
  "deviceDataCollection": {
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
    "bin": "400000"
  },
  "_actions": {
    "supply3dsDeviceData": {
      "href": "https://try.access.worldpay.com/api/payments/{linkData}/3dsDeviceData",
      "method": "POST"
    }
  }
}

After Device Data Collection completes, resume the payment by sending the collection reference to the supply3dsDeviceData action.

{
  "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5"
}

If the issuer requires additional verification, the response from the supply3dsDeviceData action includes an outcome of 3dsChallenged.

{
  "outcome": "3dsChallenged",
  "authentication": {
    "version": "2.2.0"
  },
  "challenge": {
    "reference": "706hovL8DK1tIGGzQUV1",
    "url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "payload": "eyJtZXNzYWdlVHlwZSI6Ik..."
  },
  "_actions": {
    "complete3dsChallenge": {
      "href": "https://try.access.worldpay.com/api/payments/{linkData}/3dsChallenges",
      "method": "POST"
    }
  }
}

You must display the issuer challenge to the customer using the implementation approach for your client environment.

After the customer completes the challenge, resume the payment using the complete3dsChallenge action. No request body is required.

The issuer uses device data and certain values in the Payments API request to decide if the transaction is likely to be fraudulent.
How this data is interpreted varies by issuer. Supplying more data increases the chances of the outcome being frictionless (without a challenge).
Some issuers may fail the authentication entirely without the recommended fields.

Below is our latest guide on what to include.

Objects used for 3DS authentication:

• cardNumber, billingAddress - core payment details
• instruction.threeDS - for 3DS specific data, some are mandatory
• instruction.customer - firstName, lastName, email, phone, dateOfBirth, ipAddress

• instruction.paymentInstrument.cardHolderName
• instruction.customer.email ¹
• instruction.customer.firstName ²
• instruction.customer.lastName ²
• instruction.customer.phoneNumber ¹

¹ Either customer.email or customer.phoneNumber are required.

² Only required if instruction.paymentInstrument.cardHolderName is not provided.

The following are considered mandatory by EMVco and are already part of Device Data Collection. We recommend providing these in the API request along with other device values to maximize authentication rates if Device Data Collection fails.

• instruction.threeDS.deviceData.browserScreenWidth ¹
• instruction.threeDS.deviceData.browserScreenHeight ¹
• instruction.customer.ipAddress

¹ Provide for web/browser integration only.

• instruction.paymentInstrument.billingAddress.city
• instruction.paymentInstrument.billingAddress.country
• instruction.paymentInstrument.billingAddress.address1
• instruction.paymentInstrument.billingAddress.postalCode
• instruction.paymentInstrument.billingAddress.state

In the event the Device Data Collection fails to run (browser/native), additionally provide the following in the payment request to maintain healthy authentication rates and reduce issuer challenges:

• instruction.customer.ipAddress ¹
• instruction.threeDS.deviceData.browserLanguage
• instruction.threeDS.deviceData.browserScreenHeight
• instruction.threeDS.deviceData.browserScreenWidth
• instruction.threeDS.deviceData.browserJavaEnabled
• instruction.threeDS.deviceData.browserColorDepth
• instruction.threeDS.deviceData.timeZone
• instruction.threeDS.deviceData.browserJavascriptEnabled
• instruction.threeDS.deviceData.channel ¹

¹ Only these values apply to (iOS/Android), the others are not applicable.

A summary of the 3DS authentication is included in the final payment response when available.

{
  "threeDS": {
    "type": "integrated",
    "outcome": "authenticated",
    "issuerResponse": "frictionless",
    "version": "2.2.0",
    "eci": "05"
  }
}

Authentication outage exemptions are currently not part of the default merchant setup. Please speak to your Worldpay Implementation Manager to enable this feature.

Once enabled, you can set threeDS.exemptionOnOutage to true in the request.

{
  "threeDS": {
    "type": "integrated",
    "mode": "always",
    "exemptionOnOutage": true
  }
}

The exemption increases the likelihood of receiving a successful authorization if a 3DS network outage occurs, but the transaction is not eligible for liability shift.

The response body includes the following if an authentication outage exemption is used:

{
  "threeDS": {
    "outcome": "authenticationOutage"
  }
}

Next steps

• SCA Exemptions
  
• Testing (3DS tab) for scenario details and magic test values