Last Updated: 08 October 2024 | Change Log

SDK and Device data initialization

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

Device data collection is used by the card issuer to fingerprint the customer's device. Along with the risk data in the authentication request it's used to decide if a challenge is required or if the authentication can be frictionless (no challenge displayed to your customer).

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.

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 same Device Data Initialize request as web for simplicity.

Warning

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

Device data initialization example request

Note

You must use v3 and above of the API for the Android/iOS SDK

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

Initialize the device data collection without a payment instrument. Only the JWT is returned.

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  }
}

transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference for authentication. For example, e-commerce order code. Use the same transactionReference across all 3 potential request types (deviceDataInitialization, authentication, verification).

merchantobjectrequired

An object that contains information about the merchant and API level configuration.

entitystring[ 1 .. 64 ] characters^[A-Za-z0-9 ]*$required

Used to route the request in Access Worldpay, created as part of on-boarding.

paymentInstrumentany

Device data initialization response

Note

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.

Only JWT returned

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

The DeviceDataCollection object will be used for the next step.

jwtstring[ 1 .. 2048 ] charactersrequired

A digitally signed token that contains additional details required for DDC.

urlstring[ 1 .. 2048 ] charactersrequired

A POST action on the DDC form. Used to redirect to the issuers DDC page.

binstring= 6 characters

First six digits of the card number (Bank Identification Number), used as part of DDC. Returned if a token resource, network payment token or card number is included in the request.

In case of an error, you can get further information in our error 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.7
iOS: v2.2.5

Setup the Cardinal SDK / Initial call to Cardinal

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

Next steps

Authentication