Skip to content
Preview only

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

Estimated availability: Late 2026

Last updated: 28 October 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 frontendCustomeropt[Issuer Challenge response]Authentication request1Authentication response2Redirect URL3Submit redirect URL4Collect customer browser data (hidden)5Display challenge (visible)6postMessage with outcome e.g. 3dsAuthenticated7complete8Request /{authenticationId}9Response Full details e.g. authenticationValue, eci10
3DS API3DS hosted pageMerchant backendMerchant frontendCustomer3DS API3DS hosted pageMerchant backendMerchant frontendCustomeropt[Issuer Challenge response]Authentication request1Authentication response2Redirect URL3Submit redirect URL4Collect customer browser data (hidden)5Display challenge (visible)6postMessage with outcome e.g. 3dsAuthenticated7complete8Request /{authenticationId}9Response Full details e.g. authenticationValue, eci10

Get started

Get started using our API reference.

Authentication request

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

Authentication response

Response

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

{ "outcome": "3dsRedirect", "authenticationId": "3dsC8zjGP_rRfPY5_WTbqKQM1", "redirect": "https://hpp-sandbox.worldpay.com/eu/hosted-3ds/integration/3dsC8zjGP_rRfPY5_WTbqKQM1", "_links": { "self": { "href": "https://try.access.worldpay.com/3ds/authentications/3dsC8zjGP_rRfPY5_WTbqKQM1" }, "queryAuthentication": { "href": "https://try.access.worldpay.com/3ds/authentications/3dsC8zjGP_rRfPY5_WTbqKQM1" } } }

Issuer device data and challenge

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

  • The redirect url lasts 15 minutes once issued.
  • The url can only be used once. If submitted in parallel the second will result in an action.error postMessage.
  • For completed requests action.done will be returned immediately.

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://hpp-sandbox.worldpay.com
  • Live - https://hpp.worldpay.com

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

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)

{
  "jsonrpc": "2.0",
  "id": "bd7566dc-5c99-4054-a1b8-f897fc04125a",
  "method": "action.ready",
  "params": {
    "id": "3dsC8zjGP_rRfPY5_WTbqKQM1",
    "version": "2026-08-25"
  }
}

To child frame (response)

{
  "jsonrpc": "2.0",
  "id": "bd7566dc-5c99-4054-a1b8-f897fc04125a",
  "result": {}
}

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 for values and meaning. Perform a query request to retrieve the details.

Canonical payload

{
  "jsonrpc": "2.0",
  "method": "action.done",
  "params": {
    "id": "3dsC8zjGP_rRfPY5_WTbqKQM1",
    "outcome": "3dsAuthenticated"
  }
}

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 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.
3dsErrorError details for when a downstream failure happens during redirect url POST.
3dsBypassed3DS bypassed based on rules or recommendation from authentication optimization service.
3dsExemptedSuccessful exemption in 3DS authentication.
3dsAlreadyAuthenticatedThe provided token is already SCA compliant. E.g. the Google encrypted payload provided is 3DS_CRYPTOGRAM (authenticated) and not PAN_ONLY.

Query request

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

  • The authentication outcome data is held for 15 minutes. After this, a query on the authenticationId returns a 404 authenticationNotFound.
curl
curl -i -X GET \
  -u '<username>:<password>' \
  'https://try.access.worldpay.com/3ds/authentications/{authenticationId}' \
  -H 'WP-Api-Version: 2026-10-01'

Query response

Response

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/3dsC8zjGP_rRfPY5_WTbqKQM1" } } }