# Initiate the 3DS authentication

Authenticate your customer by submitting order and risk data.

Endpoint: POST /verifications/customers/3ds/authentication
Version: 3
Security: BasicAuth

## Header parameters:

  - `Content-Type` (string)
    Example: "application/vnd.worldpay.verifications.customers-v3.hal+json"

  - `Accept` (string)
    Example: "application/vnd.worldpay.verifications.customers-v3.hal+json"

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

  - `transactionReference` (string, 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).

  - `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.

  - `merchant.overrideName` (string)
    Used to override the merchant name that's both submitted to issuers as well as displayed to the customer in the authentication process. PayFac merchants should submit the name of their submerchant.

  - `merchant.acquirerId` (string)
    Instructs the issuer that the following authorization will be completed with an external acquirer
    Example: "01234567"

  - `instruction` (object, required)
    The object that contains all the payment information related to the authentication request.

  - `instruction.value` (object, required)
    An object that contains information about the value of the authentication.

  - `instruction.value.amount` (integer, required)
    The authentication amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our [currency table](/products/reference/supported-countries-currencies#iso-currency-codes). The authentication amount should be equal to the authorization amount. We recommend you delay authentication until the amount is known, or ensure it's greater than the total transaction amount.

  - `instruction.value.currency` (string, required)
    The three digit currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes)

  - `instruction.paymentInstrument` (any, required)
    An object that contains the card details or token location.

  - `deviceData` (object, required)
    Object containing device data information.

  - `deviceData.acceptHeader` (string, required)
    Used by the issuer to check if the customer's browser is compatible with the issuer challenge display.

  - `deviceData.userAgentHeader` (string, required)
    Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321 E.g. Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0).

  - `deviceData.collectionReference` (string)
    For web this is the sessionId in the post message response from the Device Data Collection form. For iOS/Android SDK this is the consumerSessionId returned as part of SDK initialization. It is __highly recommended__ you provide this, not doing so will increase issuer challenges.

  - `deviceData.browserLanguage` (string)
    Your customer's browser language that can be used by the issuer in risk analysis. Must conform to the language tags defined by IETF. E.g. en-GB, fr-FR.

  - `deviceData.ipAddress` (string)
    A unique identifier for your customer's physical location that
            can be used by the issuer in risk analysis. Must be in IPv4 or IPv6 format.
E.g. 192.0.0.0.

  - `deviceData.browserJavaEnabled` (boolean)
    Defines whether Java is enabled on your customers browser.

  - `deviceData.browserColorDepth` (string)
    The color depth of your customers browser
    Enum: "1", "4", "8", "15", "16", "24", "32", "48"

  - `deviceData.browserScreenHeight` (integer)
    Defines the pixel height of the customers browser.

  - `deviceData.browserScreenWidth` (integer)
    Defines the pixel width of the customers browser.

  - `deviceData.timeZone` (string)
    Time zone offset in minutes between UTC and your customer's browser local time.  
Example time zone offset values in minutes:  
If UTC -5 hours:  
300  
+300  
If UTC +5 hours:  
-300

  - `deviceData.browserJavascriptEnabled` (boolean)
    Defines whether Javascript is enabled on your customers browser.

  - `challenge` (object, required)
    An object that contains challenge related information.

  - `challenge.returnUrl` (string, required)
    URL the issuer will use to notify the challenge has been completed.

  - `challenge.preference` (string)
    Preference regarding issuer displaying challenge to the customer. The interpretation of this field varies from issuer to issuer, so we cannot guarantee any particular behavior on their part as a result of you setting this field.
    Enum: "noPreference", "noChallengeRequested", "challengeRequested", "challengeMandated", "noChallengeRequestedTRAPerformed"

  - `challenge.windowSize` (string)
    Specify the challenge window size (width x height) that the issuer should use.
    Enum: "390x400", "250x400", "500x600", "600x400", "fullPage"

  - `riskData` (object)
    Object containing additional risk data.

  - `riskData.account` (object)
    Object containing all customer account related risk data.

  - `riskData.account.previousSuspiciousActivity` (boolean)
    Whether there is a record of previous suspicious activity.

  - `riskData.account.type` (string)
    Type of account the current customer has.
    Enum: "guestUser", "registeredUser", "federatedAccount", "issuerCredentials", "thirdPartyAuthentication", "fidoAuthenticator"

  - `riskData.account.email` (string)
    The customer's email address. We recommend you provide at least one of either transaction.phoneNumber or account.email

  - `riskData.account.history` (object)
    Object containing customer's account history.

  - `riskData.account.history.createdAt` (string)
    When the account was created.

  - `riskData.account.history.modifiedAt` (string)
    When the account was last modified.

  - `riskData.account.history.passwordModifiedAt` (string)
    When the account password was last changed.

  - `riskData.account.history.paymentAccountEnrolledAt` (string)
    Date the payment account was added to the cardholder account.

  - `riskData.transaction` (object)
    Object containing all customer transaction related risk data.

  - `riskData.transaction.reorder` (boolean)
    If this is a repeat of a previous order.

  - `riskData.transaction.preOrderDate` (string)
    Expected date that a pre-ordered purchase will be available.

  - `riskData.transaction.firstName` (string)
    Customer's first name.

  - `riskData.transaction.lastName` (string)
    Customer's last name.

  - `riskData.transaction.phoneNumber` (string)
    Customer's phone number.

  - `riskData.transaction.history` (object)
    Object containing details of the last transaction.

  - `riskData.transaction.history.attemptsLastDay` (integer)
    Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.

  - `riskData.transaction.history.attemptsLastYear` (integer)
    Number of transactions (successful or abandoned) for this cardholder account within the last year.

  - `riskData.transaction.history.completedLastSixMonths` (integer)
    Number of purchases with this customer account during the previous six months.

  - `riskData.transaction.history.addCardsLastDay` (integer)
    Number of attempts to add a card in the last 24hrs.

  - `riskData.transaction.history.shippingAddressFirstUsedAt` (string)
    When the shipping address used for the transaction was first used.

  - `riskData.transaction.giftCardsPurchase` (object)
    Object containing information on whether the order is being used to purchase a gift card.

  - `riskData.transaction.giftCardsPurchase.totalValue` (object)
    Object containing information on value of the gift cards being purchase.

  - `riskData.transaction.giftCardsPurchase.totalValue.amount` (integer, required)
    The amount being placed on the gift card. If provided, must include totalValue.currency.

  - `riskData.transaction.giftCardsPurchase.totalValue.currency` (string, required)
    The three digit currency code. If provided must include totalValue.amount.

  - `riskData.transaction.giftCardsPurchase.quantity` (integer)
    The number of gift cards being purchased.

  - `riskData.shipping` (object)
    Object containing all data related to how the order will be shipped.

  - `riskData.shipping.nameMatchesAccountName` (boolean)
    If customer name on account is identical to the shipping name.

  - `riskData.shipping.method` (string)
    Field containing information on shipping method chosen by customer.
    Enum: "billingAddress", "verifiedAddress", "otherAddress", "store", "digital", "unshippedTickets", "other"

  - `riskData.shipping.timeFrame` (string)
    Timeframe chosen by customer for delivery.
    Enum: "electronic", "twoDaysPlus", "nextDay", "sameDay"

  - `riskData.shipping.email` (string)
    The email address used for an electronic delivery.

  - `riskData.shipping.address` (object)
    An object containing the shipping address information.

  - `riskData.shipping.address.address1` (string, required)
    Shipping address line 1

  - `riskData.shipping.address.address2` (string)
    Shipping address line 2

  - `riskData.shipping.address.address3` (string)
    Shipping address line 3

  - `riskData.shipping.address.postalCode` (string, required)
    Postcode of shipping address

  - `riskData.shipping.address.city` (string, required)
    Shipping address city

  - `riskData.shipping.address.countryCode` (string, required)
    Shipping address country code

  - `riskData.shipping.address.stateCode` (string, required)
    Shipping address state. Should only be provided following the ISO-3611-2 two-character sub division (e.g.“CA” for California).

  - `riskData.shipping.address.phoneNumber` (string)
    Shipping recipient's phone number.

## Response 400 fields (application/vnd.worldpay.verifications.customers-v3.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` (array)
    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

  - `_links` (object)

## Response 502 fields (application/vnd.worldpay.verifications.customers-v3.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

  - `_links` (object)

## Response 503 fields (application/vnd.worldpay.verifications.customers-v3.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

  - `_links` (object)