---
title: "Authentication"
method: POST
path: "/authentications"
tags: ["authentication"]
---

# Authentication

`POST /authentications`

## Request

- Base URL: `https://try.access.worldpay.com/3ds`
- URL: `https://try.access.worldpay.com/3ds/authentications`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/worldpay/apis/3ds/docs/authentications/post.ts> (a function with typed inputs; its response is checked against the schema)

Authenticate your customer by submitting order and risk data.

## Headers

- `WP-Api-Version` '2026-10-01', required

## Request body

- 3DSAuthenticateRequest
  - `orderReference` string, required: Merchant specific reference for the order (e.g. generated ecommerce system order number). Does not have to be unique as multiple payments may apply to a single order.
  - `transactionReference` string, required: A unique reference per authentication request provided by you that is used to identify the authentication throughout its lifecycle.
  - `merchant` Merchant, required: An object that contains information about the merchant and API level configuration.
    - `entity` string, required: We use this to route your request. We create the entity as part of on-boarding.
    - `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.
    - `acquirerId` string: Instructs the issuer that the following authorization will be completed with an external acquirer.
  - `instruction` object, required: The object that contains all the payment information related to the authentication request.
    - `value` Value, required: An object that contains information about the value of the authentication.
      - `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/useful-tables/#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.
      - `currency` string, required: The three digit currency code. See list of [supported currencies](/products/reference/useful-tables/#currency-codes).
    - `paymentInstrument` union, required: An object that contains the card details or token location.
      - CardFront
        - `type` string, card/plain, required: An identifier for the `paymentInstrument` being used.
        - `cardHolderName` string: The name on your customer's card. This is not a mandatory field, however we recommend that you supply this to improve authentication rates.
        - `expiryDate` object, required: Object containing card expiry information.
          - `month` integer, required: Card expiry month.
          - `year` integer, required: Card expiry year.
        - `cardNumber` string, required: Clear card number (PAN).
        - `billingAddress` BillingAddress: An object containing the billing address information.
          - `address1` string, required: Billing address line 1.
          - `address2` string: Billing address line 2.
          - `address3` string: Billing address line 3.
          - `city` string, required: Billing address city.
          - `state` string: 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.
          - `postalCode` string, required: Billing address postal code. [See country codes with optional postalCode](/products/reference/useful-tables/#postalcode-optional).
          - `countryCode` string, required: Billing address country code.
      - CardTokenized
        - `type` string, card/token, required: An identifier for the `paymentInstrument` being used.
        - `href` string, required: An `http` address that contains your link to an Access Token.
      - CardNetworktoken
        - `type` string, card/networkToken, required: An identifier for the `paymentInstrument` being used.
        - `expiryDate` object, required: Object containing card expiry information
          - `month` integer, required: Card expiry month.
          - `year` integer, required: Card expiry year.
        - `tokenNumber` string, required: The network token number.
        - `cardHolderName` string: 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` BillingAddress: An object containing the billing address information.
          - `address1` string, required: Billing address line 1.
          - `address2` string: Billing address line 2.
          - `address3` string: Billing address line 3.
          - `city` string, required: Billing address city.
          - `state` string: 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.
          - `postalCode` string, required: Billing address postal code. [See country codes with optional postalCode](/products/reference/useful-tables/#postalcode-optional).
          - `countryCode` string, required: Billing address country code.
      - GooglepayEncrypted
        - `type` 'googlepay/encrypted', required: An identifier for the `paymentInstrument` being used.
        - `walletToken` string, required
        - `billingAddress` BillingAddress: An object containing the billing address information.
          - `address1` string, required: Billing address line 1.
          - `address2` string: Billing address line 2.
          - `address3` string: Billing address line 3.
          - `city` string, required: Billing address city.
          - `state` string: 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.
          - `postalCode` string, required: Billing address postal code. [See country codes with optional postalCode](/products/reference/useful-tables/#postalcode-optional).
          - `countryCode` string, required: Billing address country code.
  - `deviceData` DeviceData, required: Object containing device data information.
    - `acceptHeader` string, required: Used by the issuer to check if the customer's browser is compatible with the issuer challenge display.
    - `userAgentHeader` string, required: Used by issuers as part of risk analysis and to correctly display the challenge. Must conform to RFC 7321 e.g. `Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)`.
    - `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.
    - `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.
    - `browserJavaEnabled` boolean: Defines whether Java is enabled on your customer's browser.
    - `browserColorDepth` integer: The color depth of your customers browser. Between 1 and 99.
    - `browserScreenHeight` integer: Defines the pixel height of the customers browser.
    - `browserScreenWidth` integer: Defines the pixel width of the customers browser.
    - `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`
    - `browserJavascriptEnabled` boolean: Defines whether Javascript is enabled on your customer's browser.
    - `channel` 'browser' | 'native' | 'ucpBrowser': The channel used e.g. browser.
  - `customer` Customer
    - `firstName` string: Customer's first name.
    - `lastName` string: Customer's last name.
    - `phone` string: Customer's phone number.
    - `email` string: Customer's email address used for the ecommerce account.
  - `challenge` Challenge: An object that contains challenge related information.
    - `preference` 'noPreference' | 'noChallengeRequested' | 'challengeRequested' | 'challengeMandated' | 'noChallengeRequestedTRAPerformed': 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.
  - `previousSuspiciousActivity` boolean: Has the account been flagged for suspicious activity.
  - `userType` 'guestUser' | 'registeredUser' | 'federatedAccount' | 'issuerCredentials' | 'thirdPartyAuthentication' | 'fidoAuthenticator'
  - `accountHistory` AccountHistory: Customer account history.
    - `createdAt` string, date: When the account was created. Provide in ISO 8601 format.
    - `modifiedAt` string, date: When the account was last modified. Provide in ISO 8601 format.
    - `passwordModifiedAt` string, date: When the account password was last changed. Provide in ISO 8601 format.
    - `paymentAccountEnrolledAt` string, date: Date the payment account was added to the cardholder account. Provide in ISO 8601 format.
  - `reorder` boolean: Repeat of a previous order.
  - `preOrderDate` string, date: Expected date that a pre-ordered purchase will be available. Provide in ISO 8601 format.
  - `transactionHistory` TransactionHistory: Object containing details of the last transaction.
    - `attemptsLastDay` integer: Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
    - `attemptsLastYear` integer: Number of transactions (successful or abandoned) for this cardholder account within the last year.
    - `completedLastSixMonths` integer: Number of purchases with this customer account during the previous six months.
    - `addCardsLastDay` integer: Number of attempts to add a card in the last 24hrs.
    - `shippingAddressFirstUsedAt` string, date: When the shipping address used for the transaction was first used. Provide in ISO 8601 format.
  - `giftCardsPurchase` PaymentsGiftCardsPurchase: If the order is being used to purchase a gift card.
    - `totalValue` Value: An object that contains information about the value of the authentication.
      - `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/useful-tables/#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.
      - `currency` string, required: The three digit currency code. See list of [supported currencies](/products/reference/useful-tables/#currency-codes).
    - `quantity` integer: The number of gift cards being purchased.
  - `shipping` Shipping
    - `nameMatchesAccountName` boolean: If customer name on account is identical to the shipping name.
    - `method` 'billingAddress' | 'verifiedAddress' | 'otherAddress' | 'store' | 'digital' | 'unshippedTickets' | 'other': The shipping method used.
    - `timeFrame` 'electronic' | 'sameDay' | 'nextDay' | 'twoDaysPlus'
    - `email` string: The email address used for an electronic delivery.
    - `phone` string: The phone number used for delivery.
    - `firstName` string: First name used on the shipping address.
    - `lastName` string: Last name used on the shipping address.
    - `address` PaymentsShippingAddress
      - `address1` string, required: Address line 1.
      - `address2` string: Address line 2.
      - `address3` string: Address line 3.
      - `postalCode` string, required: Address postal code.
      - `city` string, required: Address city.
      - `stateCode` string: Shipping address state. Should only be provided following the `ISO-3611-2` two-character sub division (e.g.“CA” for California).
      - `countryCode` string, ISO 3166-1 alpha-2, required: The supported ISO 3166-1 alpha-2 country code.

## Response `200`

The authentication has been created.

- 3DSAuthenticate200ResponseRedirect
  - `outcome` '3dsRedirect': Client-side 3DS interaction is required. Load the `redirect` URL to run device data collection and, if the issuer requires it, a challenge.
  - `authenticationId` string: Unique identifier for a single 3ds authentication, generated by Worldpay
  - `redirect` string: Worldpay hosted URL that runs the client-side 3DS interactions with the card issuer: device data collection (DDC) and, if the issuer requires it, the challenge. The outcome is sent to your page by postMessage from the Worldpay origin. When the client-side flow is complete, use the query request with the `authenticationId` to retrieve the authentication result.
  - `_links` object
    - `self` SelfLink: Link to this 3DS authentication resource.
      - `href` string
    - `queryAuthentication` QueryAuthenticationLink: Link to query the latest state and outcome of this 3DS authentication. Use it after the client-side flow is complete.
      - `href` string

## Other responses

- `400`: The request has encountered validation errors.
- `502`: Invalid response received from upstream.
- `503`: The requested service is unavailable.

---

[API](https://skmtc.dev/worldpay/apis/3ds.md) - [All operations](https://skmtc.dev/worldpay/apis/3ds/llms.txt) - [OpenAPI document](https://skmtc.dev/worldpay/apis/3ds/revisions/0233a51762d3?raw)