# Authentication

Authenticate your customer by submitting order and risk data.

Endpoint: POST /authentication
Version: 2026-12-01
Security: BasicAuth

## Header parameters:

  - `WP-Api-Version` (string, required)
    The API version.
    Enum: "2026-12-01"

## Request fields (application/json):

  - `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.
    Example: "order-1234"

  - `transactionReference` (string)
    A unique reference per authentication request provided by you that is used to identify the authentication throughout its lifecycle.
    Example: "request-5678"

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

  - `merchant.entity` (string, required)
    We use this to route your request. We create the entity as part of on-boarding.
    Example: "default"

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

  - `instruction.value.currency` (string, required)
    The three digit currency code. See list of [supported currencies](/products/reference/useful-tables/#currency-codes).
    Example: "GBP"

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

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

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

  - `deviceData.userAgentHeader` (string)
    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).

  - `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 customer's browser.

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

  - `deviceData.browserScreenHeight` (integer)
    Defines the pixel height of the customer's browser.

  - `deviceData.browserScreenWidth` (integer)
    Defines the pixel width of the customer's 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 customer's browser.

  - `customer` (object)

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

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

  - `customer.phone` (string)
    Customer's phone number.

  - `customer.email` (string)
    Customer's email address used for the ecommerce account.

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

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

  - `previousSuspiciousActivity` (boolean)
    Has the account been flagged for suspicious activity.

  - `userType` (string)
    Enum: "guestUser", "registeredUser", "federatedAccount", "issuerCredentials", "thirdPartyAuthentication", "fidoAuthenticator"

  - `accountHistory` (object)
    Customer account history.

  - `accountHistory.createdAt` (string)
    Date the customer account was created.

  - `accountHistory.modifiedAt` (string)
    Date the customer account was last modified.

  - `accountHistory.passwordModifiedAt` (string)
    Date the password for the customer account was last modified.

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

  - `reorder` (boolean)
    Repeat of a previous order.

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

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

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

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

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

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

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

  - `giftCardsPurchase` (object)
    If the order is being used to purchase a gift card.

  - `giftCardsPurchase.totalValue` (object)
    An object that contains information about the value of the authentication.

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

  - `shipping` (object)

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

  - `shipping.method` (string)
    The shipping method used.
    Enum: "billingAddress", "verifiedAddress", "otherAddress", "store", "digital", "unshippedTickets", "other"

  - `shipping.timeFrame` (string)
    Enum: "electronic", "sameDay", "nextDay", "twoDaysPlus"

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

  - `shipping.phone` (string)
    The phone number used for delivery.

  - `shipping.firstName` (string)
    First name used on the shipping address.

  - `shipping.lastName` (string)
    Last name used on the shipping address.

  - `shipping.address` (object)

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

  - `shipping.address.address2` (string)
    Address line 2.

  - `shipping.address.address3` (string)
    Address line 3.

  - `shipping.address.postalCode` (string, required)
    Address postal code.

  - `shipping.address.city` (string, required)
    Address city.

  - `shipping.address.state` (string)
    Address state.

  - `shipping.address.countryCode` (string, required)
    The supported ISO 3166-1 alpha-2 country code.

## Response 200 fields (application/json):

  - `outcome` (string)
    Redirect.
    Enum: "3dsRedirect"

  - `authenticationId` (string)
    Unique identifier generated by us.
* 25 characters total
* 3 char prefix 3ds
* 21 nanoid 
* 1 char suffix -  currently always 0 (reserved for global traffic routing as part of a future state of Worldpay.)
    Example: "3dsLfC-vuhv7J2nEw2m9ca_e0"

  - `redirect` (string)
    The URL to redirect your customer to.

  - `_links` (object)

  - `_links.self` (object)

  - `_links.self.href` (string)

## Response 400 fields (application/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/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/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)