Menu

SDK and Device data initialization

API v3
Last updated January 2023
Change log

The card issuer uses Device Data Collection (DDC) to fingerprint the customer's device.

Along with the risk data in theauthenticationrequest it's used to decide if achallengeis required or if the authentication can be frictionless (no challenge displayed to shopper). This step is required for the authentication to use 3DS2.

Device data initialization

This request creates a JSON Web Token (JWT) that is used as part of the SDK initialization and device data collection. Whilst the web integration captures browser details the App SDK gathers information about the users mobile device.

POST your device data initialization request to the 3ds:deviceDataInitialize action link.

Note: Unlike the web integration you do not need to request and use the BIN for device data collection purposes. If your integration involves both Web and Android/iOS, you could use the sameDevice Data Initializerequest as Web for simplicity.

Important: You should only request the device data initialization API from your backend system. You should not call it directly from the mobile application using the Access credentials.

Device data initialization example request

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

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

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    }
}
ParameterMandatoryDescription
transactionReferenceA unique reference for authentication. For example, e-commerce order code.
Use the same transactionReference across all 3 potential request types (deviceDataInitialization, authentication, verification).
merchant.entityUsed to route the request in Access Worldpay, created as part of on-boarding.

Device data initialization response

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.

Copied!
{
    "outcome": "initialized",
    "transactionReference": "Memory265-13/08/1876",
    "deviceDataCollection": {
        "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiJPcmdVbml0IiwiaXNzIjoiYXBpSWQiLCJleHAiOjE1NjI5MjMzNDYsImlhdCI6MTU2MjkyMzQwNiwianRpIjoiYTAzMWVhOGEtN2E0Zi00YTQwLWI1NjMtOTUzMzYzMzVhZGNmIn0.0IK74OIXBxFsxqeOURJz1TFnz14ZTbFJTdTWo9cHUJQ",
        "url": "https://ddcUrl.example.com"
    },
    "_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"
        }]
    }
}
ParameterDescription
deviceDataCollection.jwtA digitally signed token that contains additional details required for device data collection. Expires in 10 minutes for both Try and Production.
deviceDataCollection.urlA POST action on the device data collection form. Used to redirect to the issuers device data collection page. Only used for the web integration

Note: In case of an error, you can get further information in ourerror reference.

SDK initialization

The Access 3DS API is periodically tested against the latest version of the Cardinal SDK. Current tested Cardinal SDK version:

  • Android: v2.2.6
  • iOS: v2.2.5

Setup the Cardinal SDK

Initial call to Cardinal and response

From this you will receive the consumerSessionId for use in theauthentication request

Next steps

Authentication