# Generate required data for 3DS Device Data Collection

Allow card issuers to perform Device Data Collection to fingerprint your customer's device.

Endpoint: POST /verifications/customers/3ds/deviceDataInitialize
Version: 2
Security: BasicAuth

## Security:

  - `BasicAuth` (unknown)
    http basic

## Header parameters:

  - `Content-Type` (string, required)

  - `Accept` (string, required)

## Request fields (application/vnd.worldpay.verifications.customers-v2.hal+json):

  - `transactionReference` (string, required)
    A unique reference for authentication. For example, e-commerce order code.

  - `merchant` (object, required)
    An object that contains information about the merchant and API level configuration.

  - `merchant.entity` (string, required)
    Used to route the request in Access Worldpay, created as part of on-boarding.

  - `paymentInstrument` (any)

  - `paymentInstrument.type` (string, required)
    An identifier for the `paymentInstrument` being used.
    Enum: "card/front", "card/tokenized"

  - `paymentInstrument.cardHolderName` (string, required)
    The name on the customer's card.

  - `paymentInstrument.cardExpiryDate` (object, required)
    Object containing card expiry information

  - `paymentInstrument.cardExpiryDate.month` (integer, required)
    Card expiry month

  - `paymentInstrument.cardExpiryDate.year` (integer, required)
    Card expiry year

  - `paymentInstrument.cardNumber` (string, required)
    Clear card number (PAN)

  - `paymentInstrument.billingAddress` (object)
    An object containing the billing address information.

  - `paymentInstrument.billingAddress.city` (string, required)
    Billing address city

  - `paymentInstrument.billingAddress.address1` (string, required)
    Billing address line 1

  - `paymentInstrument.billingAddress.postalCode` (string, required)
    Billing address postal code

  - `paymentInstrument.billingAddress.countryCode` (string, required)
    Billing address country code

  - `paymentInstrument.billingAddress.state` (string)
    Billing address state. Should only be provided following the `ISO-3611-2` two-character sub division (e.g.“CA” for California).

  - `paymentInstrument.billingAddress.address2` (string)
    Billing address line 2

  - `paymentInstrument.billingAddress.address3` (string)
    Billing address line 3

  - `paymentInstrument.href` (string, required)
    An `http` address that contains your link to an Access Token

  - `paymentInstrument.type` (string, required)
    Enum: "card/wallet+googlepay"

  - `paymentInstrument.walletToken` (string, required)
    The encrypted wallet token returned by Google
    Example: {"protocolVersion":"ECv1","signature":"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\u003d\u003d","signedMessage":"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7…

  - `paymentInstrument.billingAddress` (object)
    Contains the billing address information.

  - `paymentInstrument.billingAddress.address1` (string)
    First line of the address. Required if `city` is provided.

  - `paymentInstrument.billingAddress.address2` (string)
    Second line of the address.

  - `paymentInstrument.billingAddress.address3` (string)
    Third line of the address.

  - `paymentInstrument.billingAddress.city` (string)
    City. Required if `address1` is provided.

  - `paymentInstrument.billingAddress.postalCode` (string, required)
    Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`).

  - `paymentInstrument.billingAddress.state` (string)
    State/province in max 3 characters.

  - `paymentInstrument.billingAddress.countryCode` (string, required)
    Must be provided in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).

## Request examples:

  - `Initialize the device data collection for a token payment instrument` (unknown)
    Initialize the device data collection for a token payment instrument

  - `Initialize the device data collection without a payment instrument` (unknown)
    Initialize the device data collection without a payment instrument

  - `Initialize the device data collection for Google Pay` (unknown)
    Initialize the device data collection for Google Pay

## Response 200:

  - `200` (unknown)
    The data for the device data collection has been generated

## Response 200 fields (application/vnd.worldpay.verifications.customers-v2.hal+json):

  - `outcome` (string, required)
    Outcome of the device data initialization request
    Enum: "initialized", "alreadyAuthenticated"

  - `transactionReference` (string, required)
    A unique reference for authentication. For example, e-commerce order code.

  - `deviceDataCollection` (object)
    Object containing device data collection related information

  - `deviceDataCollection.jwt` (string, required)
    A digitally signed token that contains additional details required for DDC.

  - `deviceDataCollection.url` (string, required)
    A `POST` action on the DDC form. Used to redirect to the issuers DDC page.

  - `deviceDataCollection.bin` (string)
    First six digits of the card number (Bank Identification Number), used as part of DDC.

## Response 400:

  - `400` (unknown)
    The request has encountered validation errors

## Response 400 fields (application/vnd.worldpay.verifications.customers-v2.hal+json):

  - `path` (string)
    The request URI path

  - `status` (integer)
    The HTTP status returned from server

  - `message` (string, required)
    The error description message

  - `errorName` (string, required)
    The unique error name

  - `headerName` (string)
    The name of the header containing invalid value

  - `allowedMethods` (array)
    List of HTTP methods that are allowed

  - `validationErrors` (object)
    Object containing details of validation errors occurred

  - `validationErrors.errorName` (string, required)
    Unique name of the validation error

  - `validationErrors.jsonPath` (string, required)
    Location of the field in request body for which the error occurred

  - `validationErrors.message` (string, required)
    Error description message

## Response 502:

  - `502` (unknown)
    Invalid response received from upstream

## Response 502 fields (application/vnd.worldpay.verifications.customers-v2.hal+json):

  - `path` (string)
    The request URI path

  - `status` (integer)
    The HTTP status returned from server

  - `message` (string, required)
    The error description message

  - `errorName` (string, required)
    The unique error name

## Response 503:

  - `503` (unknown)
    The requested service is unavailable

## Response 503 fields (application/vnd.worldpay.verifications.customers-v2.hal+json):

  - `path` (string)
    The request URI path

  - `status` (integer)
    The HTTP status returned from server

  - `message` (string, required)
    The error description message

  - `errorName` (string, required)
    The unique error name

## Response 200 examples:

  - `Initialize the device data collection for a token payment instrument` (unknown)
    Initialize the device data collection for a token payment instrument

  - `Initialize the device data collection without a payment instrument` (unknown)
    Initialize the device data collection without a payment instrument

## Response 400 examples:

  - `The request is missing a mandatory field `transactionReference`` (unknown)
    The request does not have a mandatory field `transactionReference`

  - `The request contains an invalid `Content-Type` header` (unknown)
    The request contains an invalid `Content-Type` header

## Response 502 examples:

  - `An invalid response is received from upstream` (unknown)
    An invalid response is received from upstream

## Response 503 examples:

  - `The requested service is unavailable` (unknown)
    The requested service is unavailable