Last Updated: 18 February 2025 | Change Log

Challenge display and verification

If the authentication response outcome is challenged you can use the SDK to provide the improved 3DS2 Challenge display for mobile devices.

3DS Challenge display

You will need the following values from the authentication response to use in the SDK.

Access Name	Value from	Cardinal SDK Name
`challenge.reference`	authentication response	`transactionId`
`challenge.payload`	authentication response	`payload`

The Access 3DS API is periodically tested against the latest version of the Cardinal SDK. You can see the latest tested version in the change log

SDK challenge display

Customize challenge interface

As part of SDK setup you can customize the challenge user interface

Verification

Once the challenge has been completed, you must make a verification request to verify the result of the challenge.

Important

You should only request the verification from your backend system. You should not call it directly from the mobile application using the Access credentials.

POST your verification request to our 3ds:verify action link received in your authentication response.

Verification example request

POST https://try.access.worldpay.com/verifications/customers/3ds/verification

Verification request body:

application/vnd.worldpay.verifications.customers-v3.hal+json

An example of a verification request to return the 3DS authentication data

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "challenge": {
    "reference": "1xoKSqTvmLvhRYBsaE60"
  }
}

Response

application/vnd.worldpay.verifications.customers-v3.hal+json

An example of a verification request to return the 3DS authentication data

{
  "outcome": "authenticated",
  "transactionReference": "Memory265-13/08/1876",
  "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
  "status": "Y",
  "enrolled": "Y",
  "authentication": {
    "version": "2.1.0",
    "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "eci": "05",
    "transactionId": "c5b808e7-1de1-4069"
  }
}

Verification responses

Best Practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

Here are examples of the verification responses you would receive. To understand what these outcomes mean and how to reproduce them for testing purposes see 3DS testing.

Authenticated

description: An example of a verification request to return the 3DS authentication data
value:
  {
      "outcome": "authenticated",
      "transactionReference": "Memory265-13/08/1876",
      "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
      "status": "Y",
      "enrolled": "Y",
      "authentication": {
          "version": "2.1.0",
          "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
          "eci": "05",
          "transactionId": "c5b808e7-1de1-4069"
      }
  }

Authenticated - Cartes Bancaires

{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
    "status": "Y",
    "enrolled": "Y",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
        "eci": "05",
        "transactionId": "1be85590-d6f9-4a0b-93c9-3a7188d9a463",
        "cryptogramAlgorithm": "1",
        "challengePreference": "challengeMandated",
        "authenticationFlow": "challenge",
        "brand": "cartesBancaires"
    }
}

Apply the details (such as eci, version, authenticationValue, transactionId) required by Card Payments in the authorization request. See Testing for details.

versionstring[ 1 .. 10 ] characters

The version of 3DS used to process the transaction.

ecistring[ 1 .. 2 ] characters

Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication.

ECI	Meaning
02 or 05	Fully Authenticated Transaction
01 or 06	Attempted Authentication Transaction
00 or 07	Non 3-D Secure Transaction

Scheme	Value
Mastercard	02, 01, 00
Visa	05, 06, 07
Amex	05, 06, 07
JCB	05, 06, 07
Diners	05, 06, 07

authenticationValuestring[ 1 .. 64 ] characters

A cryptographic value that provides evidence of the outcome of a 3DS verification.

Visa - Cardholder Authentication Verification Value (CAVV)
Mastercard - Universal Cardholder Authentication Field (UCAF)

transactionIdstring[ 1 .. 64 ] characters

Directory server transaction Id, if provided should be used in the payment authorization authentication object

cryptogramAlgorithmstring[ 1 .. 99999 ] characters

Indicates the algorithm used to generate the cryptogram. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

challengePreferencestring[ 1 .. 64 ] characters

Indicates the preferred challenge behavior. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

noPreference
noChallengeRequested
challengeRequested
challengeMandated
noChallengeRequestedTRAPerformed

authenticationFlowstring[ 1 .. 64 ] characters

Indicates which flow the customer has been directed to. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

Enum"challenge""frictionless"

statusReasonstring[ 1 .. 2 ] characters

Provides further information relating to the outcome of the authentication. Returned for failed authentications only. Returned for Cartes Bancaires authentications only.

cancellationIndicatorstring[ 0 .. 2 ] characters

An indicator as to why the authentication was cancelled. Returned for Cartes Bancaires authentications only.

01 - Cardholder selected cancel
02 - Reserved for future use
03 - Authentication timed out
04 and 05 - Authentication timed out at ACS provider
06 - Transaction error
07 - Unknown
08 - Transaction timed out at SDK

networkScorestring[ 0 .. 2 ] characters

The global score calculated by the Cartes Bancaires scoring platform. Returned for Cartes Bancaires authentications only.

brandstring[ 0 .. 64 ] characters

The card brand used in the authentication. Returned for Cartes Bancaires authentications only and must be applied in the following authorization.

Next steps

Take a payment
Testing