**Last updated**: 19 May 2026 | [**Change log**](/products/payments/changelog/) # Integrated 3DS authentication 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. This guide is for `threeDS.type: "integrated"`. If you have already authenticated the customer using your own MPI, 3DS Server, PSP, or authentication provider, use [External 3DS](/products/payments/enable-features/3ds-authentication/external-3ds) instead. ## How Integrated 3DS works 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. Some authentications are frictionless. If the issuer does not require a challenge, the payment continues after Device Data Collection and proceeds to authorization. ## Integrated 3DS request 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" } } } } ``` If 3DS authentication is not available or not applicable for the payment, for example for some subsequent recurring transactions or unsupported payment methods, a validation error may be returned. View the full API request schema ## Choose your Integrated 3DS implementation guide The Integrated 3DS flow depends on your client environment. Choose the guide that matches your checkout experience. Web Use browser-based Device Data Collection and challenge display with iframes and postMessage. Android and iOS Use the Cardinal mobile SDK for native Android and iOS integrations. React Native Use React Native with WebView-based Device Data Collection and challenge flows. ## Integrated 3DS sequence diagram 3DS Web (frictionless) Card payment with [3DS authentication enabled](/products/payments/enable-features/3ds-authentication/integrated-3ds), resulting in a frictionless issuer response. ```mermaid sequenceDiagram participant Browser participant Merchant_Frontend as Merchant Frontend participant Merchant_Backend as Merchant Backend participant Payments_API as Payments API participant Issuer Browser->>Merchant_Frontend: Click Pay Merchant_Frontend->>Merchant_Backend: Pay Merchant_Backend->>Payments_API: Payment request Payments_API->>Merchant_Backend: Payment response Merchant_Backend->>Merchant_Frontend: DeviceData - BIN/JWT/URL Merchant_Frontend->>Browser: 3DS Device Data form Browser-->>Issuer: Form post Issuer-->>Browser: PostMessage: dfReferenceId Merchant_Backend->>Payments_API: 3dsDeviceData request Payments_API->>Issuer: Authorization request Issuer->>Payments_API: Authorization response Payments_API->>Merchant_Backend: 3dsDeviceData response Merchant_Backend->>Payments_API: Settlement request Payments_API->>Merchant_Backend: Settlement response Merchant_Backend->>Merchant_Frontend: Transaction complete Note left of Merchant_Frontend: Order receipt page ``` 3DS Web (challenge) Card payment with [3DS authentication enabled](/products/payments/enable-features/3ds-authentication/integrated-3ds), resulting in a challenged issuer response. ```mermaid sequenceDiagram participant Browser participant Merchant_Frontend as Merchant Frontend participant Merchant_Backend as Merchant Backend participant Payments_API as Payments API participant Issuer Browser->>Merchant_Frontend: Click Pay Merchant_Frontend->>Merchant_Backend: Pay Merchant_Backend->>Payments_API: Payment request Payments_API->>Merchant_Backend: Payment response Merchant_Backend->>Merchant_Frontend: DeviceData - BIN/JWT/URL Merchant_Frontend->>Browser: 3DS Device Data form Browser-->>Issuer: Form post Issuer-->>Browser: PostMessage: dfReferenceId Merchant_Backend->>Payments_API: 3dsDeviceData request Payments_API->>Merchant_Backend: 3dsDeviceData response Merchant_Backend->>Merchant_Frontend: Challenge JWT/URL Merchant_Frontend->>Browser: 3DS challenge form Browser-->>Issuer: Form post Issuer-->>Browser: Return to merchant site Merchant_Backend->>Payments_API: 3dsChallenges request Payments_API->>Issuer: Authorization Request Issuer->>Payments_API: Authorization Response Payments_API->>Merchant_Backend: 3dsChallenges response Merchant_Backend->>Payments_API: Settlements request Payments_API->>Merchant_Backend: Settlements response Merchant_Backend->>Merchant_Frontend: Transaction complete Note left of Merchant_Frontend: Order receipt page ``` 3DS iOS/Android (challenge) Card payment with [3DS authentication enabled](/products/payments/enable-features/3ds-authentication/integrated-3ds), resulting in a challenged issuer response. ```mermaid sequenceDiagram participant Merchant_App as Merchant App participant Merchant_Backend as Merchant Backend participant Payments_API as Payments API participant Issuer Merchant_App->>Merchant_Backend: Pay Merchant_Backend->>Payments_API: Payment request Payments_API->>Merchant_Backend: Payment response Merchant_Backend->>Merchant_App: DeviceData - JWT Note over Merchant_App: Cardinal SDK: Initialize Merchant_App-->>Issuer: Device App data Issuer-->>Merchant_App: consumerSessionId Merchant_Backend->>Payments_API: 3dsDeviceData request Note left of Payments_API: Includes consumerSessionId Payments_API->>Merchant_Backend: 3dsDeviceData response Merchant_Backend->>Merchant_App: Challenge - Payload Note over Merchant_App: Cardinal SDK: Display Challenge Merchant_App-->>Issuer: Challenge Data Issuer-->>Merchant_App: Challenge Complete Merchant_Backend->>Payments_API: 3dsChallenges request Payments_API->>Issuer: Authorization Request Issuer->>Payments_API: Authorization Response Payments_API->>Merchant_Backend: 3dsChallenges response Merchant_Backend->>Payments_API: Settlements request Payments_API->>Merchant_Backend: Settlements response Merchant_Backend->>Merchant_App: Transaction complete Note left of Merchant_App: Order receipt page ``` Example using Checkout SDK An example using the Checkout SDK to provide the card details using a low PCI set of hosted card fields. The rest of the flow is the same as the `3DS Web (challenge)` tab. ```mermaid sequenceDiagram participant Browser participant Merchant_Frontend as Merchant Frontend participant Merchant_Backend as Merchant Backend participant Payments_API as Payments API participant Checkout_Sessions as Checkout Sessions participant Issuer Note over Merchant_Frontend: Checkout JS added to page Browser->>Merchant_Frontend: Click Pay Merchant_Frontend->>Checkout_Sessions: Create session Checkout_Sessions->>Merchant_Frontend: Return session Merchant_Frontend->>Merchant_Backend: Pay Merchant_Backend->>Payments_API: Payment request Note over Merchant_Backend,Payments_API: Using Checkout SDK session Payments_API->>Merchant_Backend: Payment response Merchant_Backend->>Merchant_Frontend: DeviceData - BIN/JWT/URL Merchant_Frontend->>Browser: 3DS Device Data form Browser-->>Issuer: Form post Issuer-->>Browser: PostMessage: dfReferenceId Merchant_Backend->>Payments_API: 3dsDeviceData request Payments_API->>Merchant_Backend: 3dsDeviceData response Merchant_Backend->>Merchant_Frontend: Challenge JWT/URL Merchant_Frontend->>Browser: 3DS challenge form Browser-->>Issuer: Form post Issuer-->>Browser: Return to merchant site Merchant_Backend->>Payments_API: 3dsChallenges request Payments_API->>Issuer: Authorization Request Issuer->>Payments_API: Authorization Response Payments_API->>Merchant_Backend: 3dsChallenges response Merchant_Backend->>Payments_API: Settlements request Payments_API->>Merchant_Backend: Settlements response Merchant_Backend->>Merchant_Frontend: Transaction complete Note left of Merchant_Frontend: Order receipt page ``` ## Device Data Collection 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 you do not provide a `collectionReference`, you may see an increased number of challenged or authentication failed outcomes. ## Challenge and verification 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. If you do not complete the challenge display, the payment fails when you call the `complete3dsChallenge` action. ## How much data to provide The issuer uses [device data](/products/payments/enable-features/3ds-authentication/integrated-3ds/web#2-device-data-collection-ddc) 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](/products/payments/enable-features/3ds-authentication/web#4challenge-and-verification)). 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 ### EMVco required values - `instruction.paymentInstrument.cardHolderName` - `instruction.customer.email` 1 - `instruction.customer.firstName` 2 - `instruction.customer.lastName` 2 - `instruction.customer.phoneNumber` 1 1 Either `customer.email` or `customer.phoneNumber` are required. 2 Only required if `instruction.paymentInstrument.cardHolderName` is not provided. br 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](#device-data-collection-failure). - `instruction.threeDS.deviceData.browserScreenWidth` 1 - `instruction.threeDS.deviceData.browserScreenHeight` 1 - `instruction.customer.ipAddress` 1 Provide for web/browser integration only. #### EMVco recommended values - `instruction.paymentInstrument.billingAddress.city` - `instruction.paymentInstrument.billingAddress.country` - `instruction.paymentInstrument.billingAddress.address1` - `instruction.paymentInstrument.billingAddress.postalCode` - `instruction.paymentInstrument.billingAddress.state` ### Device Data Collection failure In the event the Device Data Collection fails to run (browser/native), additionally provide the following in the [payment request](/products/payments/openapi/payment) to maintain healthy authentication rates and reduce issuer challenges: Providing the data below directly in the API request should not be viewed as an alternative to running the [Device Data Collection form](/products/payments/enable-features/3ds-authentication/web#device-data-collection-form). It is a fallback only. - `instruction.customer.ipAddress` 1 - `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` 1 1 Only these values apply to (iOS/Android), the others are not applicable. ## Outcome details A summary of the 3DS authentication is included in the final payment response when available. Authentication successful ``` { "threeDS": { "type": "integrated", "outcome": "authenticated", "issuerResponse": "frictionless", "version": "2.2.0", "eci": "05" } } ``` Authentication successful after challenge ``` { "threeDS": { "type": "integrated", "outcome": "authenticated", "issuerResponse": "challenged", "version": "2.2.0", "eci": "05" } } ``` Authentication outage ``` { "threeDS": { "type": "integrated", "outcome": "authenticationOutage" } } ``` Authentication failed Issuer failed the authentication following the challenge. ```json { "transactionReference": "05651339-d94e-4fdd-82e9-a41d3df47c7d", "outcome": "3dsAuthenticationFailed", "authentication": { "version": "2.1.0", "eci": "07", "transactionId": "ec89944d-c5b1-4d4b-b39a-a2dc80dd5565" } } ``` Unavailable An error or timeout occurred while attempting authentication. ```json { "transactionReference": "700cb517-02c6-4dfe-a9dc-a5f77ae101bb", "outcome": "3dsUnavailable" } ``` ## Authentication outage exemptions 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. ```json { "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: ```json { "threeDS": { "outcome": "authenticationOutage" } } ``` **Next steps** - [SCA Exemptions](/products/payments/enable-features/sca-exemptions) - [Testing (3DS tab)](/products/payments/testing) for scenario details and magic test values