# Web ## 1. Add the threeDS object Adding the `threeDS` object to your payment request will enable 3DS. If 3DS authentication is not available/applicable (e.g. subsequent recurring (MIT), Apple Pay) a validation error message will be returned. Recommended Recommended key:values for high authentication rates ```JSON "instruction": { .... "threeDS": { "type": "integrated", "mode": "always", "challenge": { "returnUrl": "http://payment.example.com", }, "deviceData": { "acceptHeader": "text/html", "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)", "browserLanguage": "en-GB", "browserScreenHeight": 1200, "browserScreenWidth": 900, "browserJavaEnabled": true, "browserColorDepth": "32", "timeZone": "300", "browserJavascriptEnabled": true, "channel": "browser" } } } ``` Minimum Minimum key:values to enable 3DS ```JSON "instruction": { .... "threeDS": { "type": "integrated", "mode": "always", "challenge": { "returnUrl": "http://payment.example.com", }, "deviceData": { "acceptHeader": "text/html", "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" } } } ``` Full Request Example See [how much data to provide](/products/payments/enable-features/3ds-authentication#how-much-data-to-provide) for guidance on the values to include in the request related to 3DS, and the impact this may have on authentication rates. See [how to enable authentication outage exemptions](/products/payments/enable-features/3ds-authentication#how-to-enable-authentication-outage-exemptions) to increases the likelihood of receiving a successful authorization (without liability shift) in the event of a 3DS network failure. View the full API Request schema ## 2.Device Data Collection (DDC) The [`/payments`](/products/payments/openapi/) response will return an outcome of `3dsDeviceDatarequired`. This contains a `JWT`, `URL` and `BIN`. These values will be used for the device data collection form. ```JSON { "transactionReference": "Memory265-13/08/1876", "outcome": "3dsDeviceDataRequired", "deviceDataCollection": { "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI2NjAzMDA3YWJlMjMxZTM1ZTNmNTRjODkiLCJpc3MiOiI2NjAzMDA3YTE2ZGQ5YTdlNmEwMzM0MDciLCJleHAiOjE3MTIyNDg3MTIsImlhdCI6MTcxMjI0ODExMiwianRpIjoiZjdjZGVhZWUtMTY4MS00NjlhLTgxZmEtMzBkY2MyOTYzODA3In0.T1a6hOCPVVsQmcCKU3eczwmxlHoWK83tUqIJ_VG4fwc", "url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect", "bin": "400000" }, "_actions": { "supply3dsDeviceData": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/api/payments/eyJrIjoxLCJkIjoiR0ZSM3R2Z1d4OTI5SEdSVlVaWlk0cllQV3p4TU5raU85Y0ZwSkd2b09FWGo0SnVHYXI0MzJqZlM4RHp5UnRaaiJ9/3dsDeviceData", "method": "POST" } } } ``` ### Device Data Collection form Here's an example of how you would set up the DDC form in an iframe. 1. Create a hidden iframe and set the `src` attribute with the URL of the page that will POST the DDC form. This URL should contain in query string parameters the `deviceDataCollection.jwt`, `deviceDataCollection.bin` and `deviceDataCollection.url` as those will be used in the DDC form. ``` ``` 1. Create and host the page that POSTs the DDC form. The [Testing](/products/payments/testing) page (3DS tab) contains an example form to submit the device data values. This is useful if using tools such as Postman/Insomnia to test your integration in the early stages. ### Device Data Collection postMessage Once the DDC form is submitted and is successfully sent to the card issuer, you are notified via a [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) event. For security, verify the sender's identity using the postMessage `origin` property as detailed [here](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). | Environment | Origin | | --- | --- | | Try | https://centinelapistag.cardinalcommerce.com | | Production | https://centinelapi.cardinalcommerce.com | An example postMessage response: ``` { "MessageType": "profile.completed", "SessionId": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5", "Status": true } ``` | Key | Value | | --- | --- | | `messageType` | `profile.completed` | | `SessionId` | UUID, not present or `undefined` | | `Status` | `true` - Use the `SessionId` value in `collectionReference` as part of the `3dsDeviceData` request`false` - SessionId is empty. Either retry DDC or proceed without the `collectionReference`. | The DDC call typically takes 1-2 seconds, depending on the latency between the customer's device, the Cardinal servers and, in part, the type of Device Data Collection performed by the different issuers. The 3DS specification has the maximum response time at 10 seconds. Note If no postMessage is provided either retry DDC or send proceed without the `collectionReference`. ## 3. Continue with the payment Once device data has been completed use the `supply3dsDeviceData` action (from the `/payments` response) to resume the payment, including the `SessionId` (Aka: `collectionReference`) in the request body. ```JSON // Action to continue the payment (from /payment response) "_actions": { "supply3dsDeviceData": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/api/payments/eyJrIjoxLCJkIjoiR0ZSM3R2Z1d4OTI5SEdSVlVaWlk0cllQV3p4TU5raU85Y0ZwSkd2b09FWGo0SnVHYXI0MzJqZlM4RHp5UnRaaiJ9/3dsDeviceData", "method": "POST" } } ``` ```JSON // Include the sessionId (Aka: collectionReference) in the body { "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5" } ``` If you do not provide a `collectionReference`, you will see an increased number of `challenged` and even `authenticationFailed` outcomes. For merchants using `3DS premium` where custom rules can be created using Cardinal, you can also get a 3DS outcome of `bypassed` that will cause the payment to proceed straight to authorization after Device Data Collection. The issuer then performs a risk assessment using a combination of data from the Payments API request and the device data collection above. If it passes, the payment will proceed to `authorization`. If not, the issuer may request a `challenge` to verify the identity of the customer. ## 4.Challenge and verification If the response outcome from the `supply3dsDeviceData` action is `3dsChallenged` you must display a challenge screen from the issuer to check the customer's identity. ```JSON { "outcome": "3dsChallenged", "transactionReference": "Memory265-13/08/1876", "authentication": { "version": "2.1.0" }, "challenge": { "reference": "706hovL8DK1tIGGzQUV1", "url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI2NjAzMDA3YWJlMjMxZTM1ZTNmNTRjODkiLCJPYmplY3RpZnlQYXlsb2FkIjpmYWxzZSwiaXNzIjoiNjYwMzAwN2ExNmRkOWE3ZTZhMDMzNDA3IiwiUmV0dXJuVXJsIjoiaHR0cDovL3BheW1lbnQuZXhhbXBsZS5jb20iLCJQYXlsb2FkIjoie1wiUGF5bG9hZFwiOlwiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUppTkRKbE5UWmpaaTAyWkRrMkxUUXpNek10T0dJMk5DMWlNbVU0TldZMFpURTFaVGtpTENKaFkzTlVjbUZ1YzBsRUlqb2laV1ZqWldZeE1ETXRNRE13TVMwMFpUbGtMVGsxTmpFdE56ZGlNbVkzTlRFMk5HUmhJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQTBJbjBcIixcIkFDU1VybFwiOlwiaHR0cHM6XFwvXFwvMW1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbVxcL01lcmNoYW50QUNTV2ViXFwvY3JlcS5qc3BcIixcIlRyYW5zYWN0aW9uSWRcIjpcIjcwNmhvdkw4REsxdElHR3pRVVYxXCJ9IiwiZXhwIjoxNzEyMzA2MDk0LCJpYXQiOjE3MTIzMDU0OTQsImp0aSI6IjE4YTIwYzNkLTZhZmMtNDA5My04NGEwLTQ2OGEyYTY5MTE0OCJ9.YEpOuTxnqrXRiHan-givWBd6FfTDJOfNg-h2dF2yA6A", "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJiNDJlNTZjZi02ZDk2LTQzMzMtOGI2NC1iMmU4NWY0ZTE1ZTkiLCJhY3NUcmFuc0lEIjoiZWVjZWYxMDMtMDMwMS00ZTlkLTk1NjEtNzdiMmY3NTE2NGRhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0" }, "_actions": { "complete3dsChallenge": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/api/payments/eyJrIjoxLCJkIjoiZXlOaXNtU0lzQnVLTm5BQkt1WjEyMVFxeXg2bUZtb2hEcEpFeDdyYXZ3SDE3NFBpUTBsWUpwekptbW9hR3VVSyJ9/3dsChallenges", "method": "POST" } } } ``` #### Optional MD field Pass data specific to your checkout session and it will be echoed back in the `challenge.returnUrl` originally provided. This could, for example, be a checkout sessionId. Any value provided must be URL encoded with a maximum of 1024 characters. ### Challenge form To display the issuer's challenge screen within the iframe, use the following parameters from the response: - `challenge.url` - `challenge.jwt` 1. Create an iframe and set the `src` attribute with the URL of the page that will POST the challenge form. This URL should contain in query string parameters the `challenge.jwt`, `challenge.url` and optionally `MD` as those will be used in the challenge form. ``` ``` The size you specify for the iframe depends on whether you have provided a `challenge.windowSize` in the payments request. If not supplied use the default 400x500. 1. Create and host the page that POSTs the challenge form. Note If you get a 400 response on POST of the challenge form ensure:The JWT has not expired (10 minutes)Element/form data names are upper case e.g. `JWT` as shown in the example The [Testing](/products/payments/testing) page (3DS tab) contains an example form to submit the challenge values. This is useful if using tools such as Postman/Insomnia to test your integration in the early stages. ### Challenge returnUrl Once the issuer challenge is complete there is a `POST` to the `challenge.returnUrl` (you provide in the payments request). This will go to your backend where you can retrieve any of the form data and display a page in the iframe depending on the outcome. Form data in returnUrl POST: * `TransactionId` - same value as `challenge.reference` * `MD` - If included as part of the [challenge form](#challenge-form). ## 5. Continue with the payment Once the challenge form has been completed use the action from the `3dsDeviceData` response. No body is required. If you do not complete the challenge display the payment will fail when you post the action below. ```JSON // Action to continue the payment (from /3dsDeviceData response) "_actions": { "complete3dsChallenge": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/api/payments/eyJrIjoxLCJkIjoiZXlOaXNtU0lzQnVLTm5BQkt1WjEyMVFxeXg2bUZtb2hEcEpFeDdyYXZ3SDE3NFBpUTBsWUpwekptbW9hR3VVSyJ9/3dsChallenges", "method": "POST" } } ``` If everything is fine, the payment will proceed. However, if authentication fails or a downstream error prevents authentication details from being returned, you may encounter different outcomes. For a comprehensive overview, please refer to the [Outcome details](#6-outcome-details) below. ## 6. Outcome details A summary of the 3DS authentication is included in the final payment response . Authentication successful ```JSON ... "threeDS": { "outcome": "authenticated", "issuerResponse": "frictionless" } ... ``` Authentication outage See [how to enable authentication outage exemptions](/products/payments/enable-features/3ds-authentication#how-to-enable-authentication-outage-exemptions) ```JSON ... "threeDS": { "outcome": "authenticationOutage" } ... ``` Authentication failed Issuer failed the authentication following the challenge. { "transactionReference": "05651339-d94e-4fdd-82e9-a41d3df47c7d", "outcome": "3dsAuthenticationFailed", "authentication": { "version": "2.1.0", "eci": "07", "transactionId": "ec89944d-c5b1-4d4b-b39a-a2dc80dd5565" } } Unavailable Error/Timeout whilst attempting authentication. { "transactionReference": "700cb517-02c6-4dfe-a9dc-a5f77ae101bb", "outcome": "3dsUnavailable" }