**Last updated**: 07 April 2026 | [**Change log**](/access/products/payments/changelog/) # 3DS Authentication Enterprise SMB (Worldpay eCommerce) ## Steps in summary 1. Add the `threeDS` object to the payments request to enable 3DS. 2. A response outcome of `3dsDeviceDataRequired` will provide details to perform the issuers 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. ## Integration options Web integration API integration with a browser based client side. iOS/Android integration (native) API integration with a native client side SDK. React Native Using React Native with WebView. ## Sequence diagram 3DS Web (frictionless) Card payment with [3DS authentication enabled](/access/products/payments/enable-features/3ds-authentication), 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](/access/products/payments/enable-features/3ds-authentication), 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](/access/products/payments/enable-features/3ds-authentication), resulting in a challenged issuer response. ```mermaid sequenceDiagram participant Merchant_Frontend as Merchant Frontend 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 ``` ## How much data to provide The issuer uses [device data](/access/./3ds-authentication/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](/access/./3ds-authentication/web#4.challenge-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](/access/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](/access/./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. ## How to enable 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` as `true` in the request. ```JSON ... "threeDS": { "exemptionOnOutage": true } ... ``` The exemption increases the likelihood of receiving a successful authorization but transactions are not eligible for liability shift. The response body will contain the following if you use an authentication outage exemption. ```JSON ... "threeDS": { "outcome": "authenticationOutage" } ... ``` See our [testing guide](/access/products/payments/testing) for how to reproduce the response on the `Try` environment. **Next steps** - [SCA Exemptions](/access/products/payments/enable-features/sca-exemptions) - [Testing (3DS tab)](/access/products/payments/testing) for scenario details and magic test values