Menu

Challenge Display

API v3
Last updated January 2023
Change log

If the authentication response outcome is challenged and the authentication.version is 2.x.x (3DS2) you can use the SDK to provide the improved3DS2 Challenge displayfor mobile devices.

3DS2 Challenge display

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

Access NameValue fromCardinal SDK Name
challenge.referenceauthentication responsetransactionId
challenge.payloadauthentication responsepayload

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

SDK challenge display:

Customize Challenge Interface

As part of SDK setup you can customise 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 API 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

Note: You must use v3 of the API for the Android/iOS SDK

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

Verification request body:

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "challenge": {
        "reference": "123456789"
    }
}

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.

Copied!
{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069"
    }
}
{
    "outcome": "authenticationFailed",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
      "version": "1.0.2",
      "eci": "00",
      "transactionId": "N+en2I5+ZK/kQqk69wXdI8XIPg8="
    },
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}
{
    "outcome": "signatureFailed",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
      "version": "1.0.2",
      "eci": "02"
    },
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}
{
    "outcome": "unavailable",
    "transactionReference": "Memory265-13/08/1876",
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "3ds:verify": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/verification"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}

Use the values: version, authenticationValue, eci, transactionId from the request whenauthorizing a payment. The values prove that the verification was successful, and that the fraud liability has shifted to the issuer.

ParameterDescription
authentication.versionThe version of 3DS used to process the transaction.

Note: Required for Mastercard's Identity Check transactions in authorization.

authentication.authenticationValueA cryptographic value that provides evidence of the outcome of a 3DS verification.
  • Visa - Cardholder Authentication Verification Value (CAVV)
  • Mastercard - Universal Cardholder Authentication Field (UCAF)

Used whenauthorizing a payment.
authentication.eciElectronic Commerce Indicator (ECI).
Indicates the outcome of the 3DS authentication.
  • 02 or 05 - Fully Authenticated Transaction
  • 01 or 06 - Attempted Authentication Transaction
  • 00 or 07 - Non 3-D Secure Transaction
  • Mastercard - 02, 01, 00
  • Visa - 05, 06, 07
  • Amex - 05, 06, 07
  • JCB - 05, 06, 07
  • Diners - 05, 06, 07

You will need to use this when you areauthorizing a payment.
authentication.transactionIdA transaction identifier.
If provided, you should use it as part of yourpayment authorization.
If the authentication.version has a major version of:
  • 1 - value returned known as xid
  • 2 - value returned known as dsTransactionId

Next steps

Take a payment