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

Estimated availability: Late 2026

**Last updated**: 12 August 2026 | [**Change log**](/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](/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

```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)
    opt Issuer Challenge response
    3hfe<<-->>c: Display challenge (visible)
    end
    3hfe->>fe: postMessage with outcome <br> e.g. 3dsAuthenticated
    fe->>be: complete
    be->>3: Request /{authenticationId}
    3->>be: Response <br> Full details e.g. authenticationValue, eci
```

## Get started

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

## Authentication request

```shell curl
curl -i -X POST \
  -u <username>:<password> \
  https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications \
  -H 'Content-Type: application/json' \
  -H 'WP-Api-Version: 2026-12-01' \
  -d '{
    "orderReference": "order-1234",
    "transactionReference": "request-5678",
    "merchant": {
      "entity": "default"
    },
    "instruction": {
      "value": {
        "amount": 100,
        "currency": "GBP"
      },
      "paymentInstrument": {
        "type": "card/plain",
        "cardNumber": "4444333322221111",
        "cardHolderName": "Sherlock Holmes",
        "expiryDate": {
          "month": 1,
          "year": 2028
        },
        "billingAddress": {
          "address1": "221B Baker Street",
          "city": "London",
          "postalCode": "NW1 6XE",
          "countryCode": "GB"
        }
      }
    },
    "deviceData": {
      "acceptHeader": "text/html",
      "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    },
    "customer": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phone": "02031234321",
      "email": "sherlock.holmes@example.com"
    }
  }'
```

View the full authentication request schema
## Authentication response

```json 200 application/json
{
  "outcome": "3dsRedirect",
  "authenticationId": "3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "redirect": "https://hpp-test.worldpay-bsh.securedataplatform.com/all/hosted-threeds/3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/{authenticationId}"
    }
  }
}
```

```json 400 application/json
{
  "message": "The json body provided does not match the expected schema",
  "errorName": "bodyDoesNotMatchSchema",
  "validationErrors": [
    {
      "errorName": "stringFailedRegexCheck",
      "jsonPath": "$.merchant.entity",
      "message": "Entity must be alphanumeric with optional spaces"
    },
    {
      "errorName": "stringFailedRegexCheck",
      "jsonPath": "$.transactionReference",
      "message": "Transaction reference characters must be alphanumeric or one of the following: _!@#$%()*=-.:;?[]{}~`/+"
    }
  ],
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

```json 502 application/json
{
  "message": "Service Unavailable",
  "errorName": "serviceUnavailable",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

```json 503 application/json
{
  "message": "Service Unavailable",
  "errorName": "serviceUnavailable",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

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

You are notified of the outcome via a [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) event. For security, use a strict whitelist check against the provided Worldpay origins using the postMessage `origin` property, as detailed in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

* Try - `https://hpp-test.worldpay-bsh.securedataplatform.com`
* Live - `https://hpp.worldpay-bsh.securedataplatform.com`


For UCP (Universal Commerce Protocol) integration an additional postMessage handshake is required to initialize the redirect page.

details
summary
Details of UCP postMessage handshake
The following JSON examples are the `event.data` payloads.
`origin`, `source`, `ports`, `type`, and `lastEventId` are fields on the browser `MessageEvent` object.

To parent frame (request)

```json
{
  "jsonrpc": "2.0",
  "id": "ready-1",
  "method": "action.ready",
  "params": {
    "id": "{authenticationId}",
    "version": "{{ ucp_version }}"
  }
}
```

To child frame (response)

```json
{
  "jsonrpc": "2.0",
  "id": "ready-1",
  "result": {}
}
```

Prompt (challenge)
Preview only
The challenge postMessage design is still under review.

A `method` of value `action.prompt` means an action is required by your customer.

When a `params.outcome` is `3dsChallenged`, you must make the iframe visible (if it is not already). Your customer must authenticate with their bank and they are shown the prompt to do so (e.g. to authenticate using their banking app).

```json
{
  "jsonrpc": "2.0",
  "method": "action.prompt",
  "params": {
    "id": "3dsI-dUcet9fk4_X4qZU0hpU0",
    "outcome": "3dsChallenged"
  }
}
```

Done
A `method` of value `action.done` means the client-side interaction is complete.

For all other `params.outcome` values besides `3dsChallenged`, the client-side flow is complete ("method": "action.done"). [See the schema below](#supported-paramsoutcome-values) for values and meaning. Perform a [query request](#query-request) to retrieve the details.

#### Canonical payload

```json
{
  "jsonrpc": "2.0",
  "method": "action.done",
  "params": {
    "id": "3dsI-dUcet9fk4_X4qZU0hpU0",
    "outcome": "3dsAuthenticated"
  }
}
```

Error
When an error occurs during the client-side flow, a postMessage is returned with an `error` object.

#### Example generic error response

```json
{
  "jsonrpc": "2.0",
  "error": {
    //TBC
  }
}
```

#### Supported `params.outcome` values

Except for `3dsChallenged` (which is not the end of the flow) and `3dsRedirect` (which is completed before the postMessage takes place), the below outcomes match the [API query response](/products/3ds/20261201/openapi) values.

| Outcome value | Meaning |
|  --- | --- |
| `3dsAuthenticated` | Cardholder successfully authenticated by card issuer. |
| `3dsAttempted` | 3DS attempted but card issuer not participating. Stand-in authentication by the scheme. |
| `3dsChallenged` | Issuer requests an identity check using the challenge screen |
| `3dsChallengeFailed` | Failed cardholder challenge. |
| `3dsRejected` | Issuer rejects the authentication, do not proceed with payment. |
| `3dsNotAuthenticated` | Authentication failure by card issuer (system issue). |
| `3dsUnavailable` | Authentication unavailable at this current time. |
| `3dsOutage` | Issuer recognized outage. Can attempt authentication outage exemption. |
| `3dsBypassed` | 3DS bypassed based on rules or recommendation from authentication optimization service. |
| `3dsExempted` | Successful exemption in 3DS authentication. |


Components SDK
Provide the redirect URL to the Components 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.

```shell curl
curl -i -X GET \
  -u <username>:<password> \
  'https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/{authenticationId}' \
  -H 'WP-Api-Version: 2026-12-01'
```

View the full query request schema
## Query response

```json 200 application/json
{
  "outcome": "3dsAuthenticated",
  "status": "Y",
  "enrolled": "Y",
  "version": "2.2.0",
  "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
  "eci": "05",
  "dsTransactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645",
  "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

```json 400 application/json
{
  "message": "The json body provided does not match the expected schema",
  "errorName": "bodyDoesNotMatchSchema",
  "validationErrors": [
    {
      "errorName": "stringFailedRegexCheck",
      "jsonPath": "$.merchant.entity",
      "message": "Entity must be alphanumeric with optional spaces"
    },
    {
      "errorName": "stringFailedRegexCheck",
      "jsonPath": "$.transactionReference",
      "message": "Transaction reference characters must be alphanumeric or one of the following: _!@#$%()*=-.:;?[]{}~`/+"
    }
  ],
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

```json 502 application/json
{
  "message": "Service Unavailable",
  "errorName": "serviceUnavailable",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

```json 503 application/json
{
  "message": "Service Unavailable",
  "errorName": "serviceUnavailable",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}
```

View the full query response schema