# Initiate the 3DS authentication

Authenticate your customer by submitting order and risk data.

Endpoint: POST /verifications/customers/3ds/authenticate
Version: 1
Security: BasicAuth

## Header parameters:

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

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

## Request fields (application/vnd.worldpay.verifications.customers-v1.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.

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

  - `instruction.value.currency` (string, required)
    The three digit currency code.

  - `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 and Device data initialization.

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

  - `challenge.returnUrl` (string, required)
    URL the issuer will redirect to once the customer completes the challenge page.

  - `challenge.preference` (string)
    Preference regarding issuer displaying challenge to the customer.
    Enum: "noPreference", "noChallengeRequested", "challengeRequested", "challengeMandated"

  - `challenge.windowSize` (string)
    Specify the challenge window size (width x height) that the issuer should use.
    Enum: "390x400", "250x400", "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.

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

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

  - `outcome` (string, required)
    The outcome of the authentication request.
    Enum: "challenged", "notEnrolled", "unavailable", "authenticationFailed", "authenticated", "signatureFailed", "bypassed"

  - `transactionReference` (string)
    A unique reference for authentication that was passed in the request.

  - `authentication` (object)
    Object that contains authentication related information.

  - `authentication.version` (string)
    The version of 3DS used to process the transaction.

  - `authentication.eci` (string)
    Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication.

  - `authentication.authenticationValue` (string)
    A cryptographic value that provides evidence of the outcome of a 3DS verification.

  - `authentication.transactionId` (string)
    A transaction identifier. If provided, you should use it as part of your payment authorization.

  - `challenge` (object)
    Object containing challenge related information in case of a "challenged" flow

  - `challenge.reference` (string)
    This links the authentication response to the subsequent challenge form and verification request.

  - `challenge.url` (string)
    POST action on the challenge form. Used to redirect to the issuers challenge page as part of the challenge form.

  - `challenge.jwt` (string)
    A digitally signed token that contains additional details, such as the URL to return to after the challenge screen.

  - `challenge.payload` (string)
    JSON container with extra data required for the challenge.

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