Preview only
This is a preview of the next major version and is subject to change.

Estimated availability: Late 2026

**Last updated**: 22 April 2025 | [**Change log**](/access/products/3ds/changelog/)

# 3DS API

Verify your customer's identity to minimize fraud. Use our Strong Customer Authentication (SCA) to benefit from liability shift.

3DS allows you to meet the Strong Customer Authentication (SCA) requirement under the PSD2 regulation as well as shifting liability for fraudulent transactions to the issuer. Learn more about [when SCA applies](/access/products/3ds-sca-exemptions#when-sca-applies).

br
**Supported payment methods**: *American Express / Cartes Bancaires / Discover / Diners / EFTPOS  / JCB / Maestro / MasterCard / MasterCard Debit / Visa / Visa Debit / Visa Electron (UK only)*

## Sequence diagram

Challenge

```mermaid

sequenceDiagram
    autonumber
    participant c as Customer
    participant fe as Merchant frontend
    participant be as Merchant backend
    participant 3hfe as 3DS hosted page
    participant 3 as 3DS API
    be->>3: Authentication request
    3->>be: Authentication response
    be->>fe: Redirect URL
    fe->>3hfe: Submit redirect URL
    3hfe<<-->>c: Collect customer browser data (hidden)
    3hfe<<-->>c: Display challenge (visible)
    3hfe->>fe: postMessage with outcome <br> e.g. 3dsAuthenticated
    fe->>be: 
    be->>3: Request /{authenticationId}
    3->>be: Response <br> Full details e.g. authenticationValue, eci
```

Frictionless

```mermaid

sequenceDiagram
    autonumber
    participant c as Customer
    participant fe as Merchant frontend
    participant be as Merchant backend
    participant 3hfe as 3DS hosted page
    participant 3 as 3DS API
    be->>3: Authentication request
    3->>be: Authentication response
    be->>fe: Redirect url
    fe->>3hfe: Submit redirect url
    3hfe<<-->>c: Collect customer browser data (hidden)
    3hfe->>fe: postMessage with outcome <br> e.g. 3dsAuthenticated
    fe->>be: 
    be->>3: Request /{authenticationId}
    3->>be: Response <br> Full details e.g. authenticationValue, eci
```

## Get started

Get started using our [API reference](/access/products/3ds/20261201/openapi).

## Authentication request

View the full authentication request schema
## Authentication response

View the full authentication response schema
## Issuer device data and challenge

Perform issuer Device Data Collection (DDC), and when required, a challenge using a Worldpay hosted URL.

API only
Add the `redirect` url to an iframe to run Device Data Collection and if required by the issuer a challenge.


```html
<iframe height="1" width="1" style="display: none;" src="{replace with redirect url}"></iframe>
```

### postMessage response

You are notified of the outcome 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).

* Try - `https://try.{path-tbc}.worldpay.com`
* Live - `https://{path-tbc}.worldpay.com`


Challenge
When a `gp.3ds.challenge` postMessage is returned the iframe needs to be made visible as the customer must authenticate with their bank and is shown how to do this.


```json
{
  "type": "gp.3ds.challenge",
  "data": {
    "outcome": "3dsChallenged", 
    "windowSize": "390x400", 
    "authenticationId": "abc123"
  },
  "metadata": {
    "timestamp": "2026-01-26T15:30:45.123Z",
    "correlationId": "4340a835-aeef-4a18-a808-aa05f11531d3"
  }
}
```

Result
When a `gp.3ds.result` postMessage is returned, the clientside interaction is over and a [query request](/access/products/3ds/20261201/openapi/authentication/authenticationquery) can be performed to retrieve details.

#### Example authenticated response


```json
{
  "type": "gp.3ds.result",
  "data": {
    "outcome": "3dsAuthenticated",
    "authenticationId": "abc123"
  },
  "metadata": {
    "timestamp": "2026-01-26T15:30:45.123Z",
    "correlationId": "4340a835-aeef-4a18-a808-aa05f11531d3"
  }
}
```

#### Example rejected response


```json
{
  "type": "gp.3ds.result", 
  "data": {
    "outcome": "3dsRejected",
    "authenticationId": "abc123"
  },
  "metadata": {
    "timestamp": "2026-01-26T15:30:45.123Z",
    "correlationId": "4340a835-aeef-4a18-a808-aa05f11531d3"
  }
}
```

Other possible outcome values:

* 3dsAuthenticated
* 3dsAttempted
* 3dsRejected
* 3dsNotAuthenticated
* 3dsUnavailable
* 3dsOutage
* 3dsBypassed
* 3dsDataOnly
* 3dsExempted


Error
When a `gp.3ds.error` postMessage is returned an error occured and the 3DS authentication was not successful.

### Example error response


```json
{
  "type": "gp.3ds.error", 
  "data": {
    "error": [
      {
        // tbc
      }
    ],
    "authenticationId": "abc123"
  },
  "metadata": {
    "timestamp": "2026-01-26T15:30:45.123Z",
    "correlationId": "4340a835-aeef-4a18-a808-aa05f11531d3"
  }
}
```

Checkout SDK
Provide the redirect URL to the Checkout SDK and let it handle all aspects of running the challenge display. Receive the outcomes as callbacks.

***Coming soon....***

## Query request

Use the `authenticationId` to get the details for the current state or outcome of the 3DS authentication.

View the full query request schema
## Query response

View the full query response schema