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: 09 June 2026 | 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
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

Card authentication request with minimum recommended values

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

Use a hosted 3DS page to wrap and perform device data collection, and when prompted display a challenge from the issuer

{
  "outcome": "3dsRedirect",
  "authenticationId": "3dsLfC-Tuhv7J2nEw2m9ca_e0",
  "redirect": "https://hosted.worldpay.com/xxxxxxxxxx/redirect",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/3ds/authentications/{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

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

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

A result.event of value pa.prompt means an action is required by your customer.

When a result.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).

{
  "jsonrpc": "2.0",
  "result": {
    "event": "pa.prompt",
    "outcome": "3dsChallenged"
  },
  "data": {
    "authenticationId": "abc123"
  }
}

Schema

FieldTypeDescription
jsonrpcstringJSON-RPC protocol version.
result.eventstringHigh-level event value. For completed client-side processing this is pa.done. pa.prompt is used for issuer challenge response; processing is still required.
result.outcomestringDetailed 3DS outcome for the authentication.
data.authenticationIdstringAuthentication identifier used in the follow-up query request. Returned in all message types.
errorobjectError object returned when the postMessage indicates a failure.
error.codenumberJSON-RPC error code.
error.messagestringError message for the failure.

Supported result.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 values.

Outcome valueMeaning
3dsAuthenticatedCardholder successfully authenticated by card issuer.
3dsAttempted3DS attempted but card issuer not participating. Stand-in authentication by the scheme.
3dsChallengedIssuer requests an identity check using the challenge screen
3dsChallengeFailedFailed cardholder challenge.
3dsRejectedIssuer rejects the authentication, do not proceed with payment.
3dsNotAuthenticatedAuthentication failure by card issuer (system issue).
3dsUnavailableAuthentication unavailable at this current time.
3dsOutageIssuer recognized outage. Can attempt authentication outage exemption.
3dsBypassed3DS bypassed based on rules or recommendation from authentication optimization service.
3dsDataOnlySuccessful data only authentication.
3dsExemptedSuccessful exemption in 3DS authentication.

Example received browser event

This is the payload above as received by the parent window in a browser MessageEvent.

{
  data: {
    jsonrpc: "2.0",
    result: {
      event: "pa.done",
      outcome: "3dsAuthenticated"
    },
    data: {
      authenticationId: "abc123"
    }
  },
  origin: "https://try.{path-tbc}.worldpay.com",
  source: WindowProxy,
  ports: [],
  type: "message",
  lastEventId: ""
}

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/authentications/{authenticationId}' \
  -H 'WP-Api-Version: 2026-12-01'

View the full query request schema

Query response

Response
application/json

Successful frictionless authentication

{
  "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/3ds/authentications/LfC-Tuhv7J2nEw2m9ca_e"
    }
  }
}

View the full query response schema