**Last updated**: 22 April 2025 | [**Change log**](/products/3ds/changelog/) # SDK and device data initialization The card issuer uses Device Data Collection (DDC) to fingerprint the customer's device. DDC is used by the card issuer to fingerprint the customer's device. Along with the risk data in the [authentication](/products/3ds/android-ios/authentication) request it's used to decide if a [challenge](/products/3ds/android-ios/challenge-verification) 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 DDC. Whilst the web integration captures browser details the App SDK gathers information about the user's 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 DDC purposes. If your integration involves both Web and Android/iOS you could use the same [device data initialize](/products/3ds/web/device-data) request as web for simplicity. Warning You should only request the device data initialization 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 ```json { "$ref": "#/components/schemas/3DS_deviceDataInitialize", "components": { "schemas": { "transactionReference": { "maxLength": 64, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "A unique reference for authentication. For example, e-commerce order code. Use the same transactionReference across all 3 potential request types (deviceDataInitialization, authentication, verification)." }, "merchant": { "required": [ "entity" ], "type": "object", "description": "An object that contains information about the merchant and API level configuration.", "properties": { "entity": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9 ]*$", "type": "string", "description": "Used to route the request in Access Worldpay, created as part of on-boarding." } } }, "cardHolderName": { "maxLength": 255, "minLength": 1, "type": "string", "description": "The name on your customer's card. This is not a mandatory field, however we recommend that you supply this to improve authentication rates." }, "billingAddress": { "required": [ "address1", "city", "postalCode", "countryCode" ], "type": "object", "description": "An object containing the billing address information.", "properties": { "city": { "maxLength": 15, "minLength": 1, "type": "string", "description": "Billing address city" }, "address1": { "maxLength": 80, "minLength": 1, "type": "string", "description": "Billing address line 1" }, "postalCode": { "maxLength": 15, "minLength": 1, "type": "string", "description": "Billing address postal code, [See country codes with optional postalCode](/products/reference/supported-countries-currencies#postalcode-optional)" }, "countryCode": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string", "description": "Billing address country code" }, "state": { "maxLength": 30, "minLength": 1, "type": "string", "description": "Billing address state. Should only be provided following the `ISO-3611-2` two-character sub division (e.g.“CA” for California). We recommend you provide this for US and China addresses." }, "address2": { "maxLength": 80, "type": "string", "description": "Billing address line 2" }, "address3": { "maxLength": 80, "type": "string", "description": "Billing address line 3" } } }, "card_front": { "required": [ "type", "cardNumber", "cardExpiryDate" ], "type": "object", "properties": { "type": { "type": "string", "format": "card/front", "description": "An identifier for the `paymentInstrument` being used." }, "cardHolderName": { "$ref": "#/components/schemas/cardHolderName" }, "cardExpiryDate": { "required": [ "month", "year" ], "type": "object", "description": "Object containing card expiry information", "properties": { "month": { "maximum": 12, "minimum": 1, "type": "integer", "description": "Card expiry month" }, "year": { "maximum": 9999, "minimum": 1, "type": "integer", "description": "Card expiry year" } } }, "cardNumber": { "maxLength": 19, "minLength": 10, "pattern": "^[0-9]*$", "type": "string", "description": "Clear card number (PAN)" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" } } }, "card_tokenized": { "required": [ "type", "href" ], "type": "object", "properties": { "type": { "type": "string", "format": "card/tokenized", "description": "An identifier for the `paymentInstrument` being used." }, "href": { "minLength": 1, "type": "string", "description": "An `http` address that contains your link to an Access Token" } } }, "card_networktoken": { "required": [ "type", "tokenNumber", "cardExpiryDate" ], "type": "object", "properties": { "type": { "type": "string", "format": "card/networkToken", "description": "An identifier for the `paymentInstrument` being used." }, "cardExpiryDate": { "required": [ "month", "year" ], "type": "object", "description": "Object containing card expiry information", "properties": { "month": { "maximum": 12, "minimum": 1, "type": "integer", "description": "Card expiry month" }, "year": { "maximum": 9999, "minimum": 1, "type": "integer", "description": "Card expiry year" } } }, "tokenNumber": { "maxLength": 19, "minLength": 10, "pattern": "^[0-9]*$", "type": "string", "description": "The network token number" }, "cardHolderName": { "$ref": "#/components/schemas/cardHolderName" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" } } }, "3DS_deviceDataInitialize": { "required": [ "transactionReference", "merchant" ], "type": "object", "properties": { "transactionReference": { "$ref": "#/components/schemas/transactionReference" }, "merchant": { "$ref": "#/components/schemas/merchant" }, "paymentInstrument": { "oneOf": [ { "$ref": "#/components/schemas/card_front" }, { "$ref": "#/components/schemas/card_tokenized" }, { "$ref": "#/components/schemas/card_networktoken" } ], "discriminator": { "mapping": { "card/front": "#/components/schemas/card_front", "card/tokenized": "#/components/schemas/card_tokenized", "card/networkToken": "#/components/schemas/card_networktoken" }, "propertyName": "type" } } } } } } } ``` ### 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 ```json Only JWT returned description: Initialize the device data collection without a payment instrument. Only the JWT is returned. value: { "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-bsh.securedataplatform.com/verifications/customers/3ds/authentication" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } ``` The `DeviceDataCollection` object will be used for the next step. ```json { "$ref": "#/components/schemas/deviceDataCollection", "components": { "schemas": { "deviceDataCollection": { "required": [ "jwt", "url" ], "type": "object", "description": "Object containing device data collection related information", "properties": { "jwt": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "A digitally signed token that contains additional details required for DDC." }, "url": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "A `POST` action on the DDC form. Used to redirect to the issuers DDC page." }, "bin": { "maxLength": 6, "minLength": 6, "type": "string", "description": "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](/products/reference/worldpay-error-responses). ### 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 - Android - iOS #### Initial call to Cardinal - Android - iOS From this you will receive the `consumerSessionId` for use in the [authentication request](/products/3ds/android-ios/authentication) **Next steps** [Authentication](/products/3ds/android-ios/authentication)