Skip to content
APIs/3DS/
Get started
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

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.


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

Sequence diagram

3DS API3DS hosted pageMerchant backendMerchant frontendCustomer3DS API3DS hosted pageMerchant backendMerchant frontendCustomerAuthentication request1Authentication response2Redirect URL3Submit redirect URL4Collect customer browser data (hidden)5Display challenge (visible)6postMessage with outcome e.g. 3dsAuthenticated7​8Request /{authenticationId}9Response Full details e.g. authenticationValue, eci10

Get started

Get started using our API reference.

Authentication request

application/json
{
  "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"
      }
    }
  },
  "customer": {
    "firstName": "Sherlock",
    "lastName": "Holmes",
    "phone": "02031234321",
    "email": "sherlock.holmes@example.com"
  }
}

View the full authentication request schema

Authentication response

Response
application/json
{
  "outcome": "3dsRedirect",
  "authenticationId": "3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "redirect": "https://hosted.worldpay.com/xxxxxxxxxx/redirect",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/api/3ds/{authenticationId}"
    }
  }
}

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.

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

<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 event. For security, verify the sender's identity using the postMessage origin property as detailed here.

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

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.

{
  "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"
  }
}

Query request

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

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

View the full query request schema

Query response

Response
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.com/api/3ds/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}

View the full query response schema