Important
We have released a new version. Documentation for our latest version can be found [here](/products/3ds/).

**Last updated**: 22 April 2025 | [**Change log**](/products/3ds/changelog/)

# Authentication

`POST` your authentication request to the `3ds:authenticate` action link. Your authentication request sends order and risk data used to decide if a [challenge](/products/3ds/v1/challenge-verification#challenge-display) is required.

## Authentication example request

`POST`  `https://try.access.worldpay.com/verifications/customers/3ds/authentication`

Authentication request body:

Card
{
    "transactionReference": "Memory265-13/08/1986",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "paymentInstrument": {
            "type": "card/front",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            },
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "postalCode": "NW1 6XE",
                "city": "London",
                "state": "Greater London",
                "countryCode": "GB"
            }
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        }
    },
    "deviceData": {
        "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
        "acceptHeader": "text/html",
        "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    },
    "challenge": {
        "returnUrl": "http://returnUrl.example.com"
    }
}
Token
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        }
    },
    "deviceData": {
        "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
        "acceptHeader": "text/html",
        "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    },
    "challenge": {
        "returnUrl": "http://returnUrl.example.com"
    }
}
## How much data to provide

The [device data](/products/3ds/v1/device-data) and values in the `authentication` request are used by the issuer to decide if the transaction is likely to be fraudulent.
How this data is interpreted varies by issuer. Supplying more data increases the chances of the outcome being frictionless (without a [challenge](/products/3ds/v1/challenge-verification).
Some issuers mmay fail the authentication entirely without the recommended fields.

#### Optional data we recommend including as a minimum:

- `paymentInstrument.billingAddress` - including sub values
- `deviceData.browserScreenHeight` - EMVco Required
- `deviceData.browserScreenWidth` - EMVco Required
- `deviceData.ipAddress` - EMVco Required
- `paymentInstrument.cardHolderName` - EMVco Required
- `riskData.account.email` - one of either `account.email` or `transaction.phoneNumber`
- `riskData.transaction.phoneNumber` - one of either `account.email` or `transaction.phoneNumber`


For details see the tables below where they are clearly marked as **EMVco Required** or **EMVco Recommended**

Important
The issuer prioritizes device data collection values for risk analysis over the browser language and IP address details. We recommend you still include these details. In case of unsuccessful device data collection, the authentication may fail if you do not include them.

| Parameter | Mandatory | Description |
|  --- | --- | --- |
| `transactionReference` | ✅ | A unique reference for authentication. for example, e-commerce order code. |
| `merchant.entity` | ✅ | Used to route the authentication request in Access Worldpay, created as part of on-boarding. |
| `instruction` | ✅ | The object that contains all the payment information related to the authentication request. |
| `instruction.paymentInstrument` | ✅ | An object that contains the card details or token location. |
| `paymentInstrument.type` | ✅ | An identifier for the `paymentInstrument` being used.`type` : `card/front` See [authentication(card)](#authentication-example-request) above`type` : `card/tokenized`  See [authentication(token)](#authentication-example-request) above |
| `paymentInstrument.cardHolderName` | **EMVco Required** | The name on your customer's card. This is not a mandatory field, however we recommend that you supply this to improve authentication rates. |
| `paymentInstrument.billingAddress` | **EMVco Recommended** | An object containing the billing address information.  **If included you must send** at least:`address1``city`[`countryCode`](/products/reference/supported-countries-currencies#iso-country-codes)`postalCode` |
| `deviceData.acceptHeader` | ✅ | Used by the issuer to check if the customer's browser is compatible with the issuer challenge display. |
| `deviceData.userAgentHeader` | ✅ | Used by the issuer to check the customer's browser and operating system information. |
| `deviceData.collectionReference` | ❌ | The `session Id` in the postMessage response from the [Device Data Collection Form](/products/3ds/v1/device-data) contains this reference.  If no value is provided the authentication falls back to 3DS1. |
| `deviceData.browserLanguage` | ❌ | 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` | **EMVco Required** | A unique identifier for your customer's physical location that can be used by the issuer in risk analysis. Must be in IPv4 format. E.g. 192.0.0.0 |
| `deviceData.browserJavaEnabled` | ❌ | Defines whether Java is enabled on your customers browser |
| `deviceData.browserJavascriptEnabled` | ❌ | Defines whether Javascript is enabled on your customers browser |
| `deviceData.browserColorDepth` | ❌ | The color depth of your customers browser`1` - 1 bit`4` - 4 bits`8` - 8 bits`15` - 15 bits`16` - 16 bits`24` - 24 bits`32` - 32 bits`48` - 48 bits |
| `deviceData.browserScreenHeight` | **EMVco Required** | Defines the pixel height of the customers browser |
| `deviceData.browserScreenWidth` | **EMVco Required** | Defines the pixel width of the customers browser |
| `deviceData.timeZone` | ❌ | 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+300If UTC +5 hours:-300 |
| `challenge.windowSize` | ❌ | Specify the challenge window size that the issuer should use. This is to better tailor the experience to the customers device.`250x400``390x400``600x400``500x600``fullpage` - expand to fill viewport |
| `challenge.preference` | ❌ | `noPreference` - default`noChallengeRequested` - prefer no challenge performed`challengeRequested` - prefer challenge is performed`challengeMandated` - local or region mandates meaning a challenge must be performedYou must use `challengeMandated` when first storing cards in general (e.g. first payment where a token is stored or independently "adding a card" to an account).You should use `challengeMandated` in the authentication request as part of the first CIT payment in an MIT series or when using the Checkout SDK to take payments. The interpretation of this field varies from issuer to issuer, so Worldpay cannot guarantee any particular behavior on their part as a result of you setting this field. |
| `challenge.returnUrl` | ✅ | The path your customer will be returned to after completing the issuers [challenge screen](/products/3ds/v1/challenge-verification). Must be the full URL path |


### Optional fields in an Authentication request

details
summary
Optional fields
Markdown content here.

#### Complete Authentication request schema

Full Authentication request body:

Card
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "paymentInstrument": {
            "type": "card/front",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            },
            "billingAddress": {
                "address1": "Worldpay",
                "address2": "1 Milton Road",
                "address3": "The Science Park",
                "postalCode": "CB4 0WE",
                "city": "Cambridge",
                "state": "Cambridgeshire",
                "countryCode": "GB"
            }
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        }
    },
    "deviceData": {
        "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
        "acceptHeader": "text/html",
        "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    },
    "challenge": {
        "windowSize": "600x400",
        "preference": "noPreference",
        "returnUrl": "http://returnUrl.example.com"
    },
    "riskData": {
        "account": {
            "previousSuspiciousActivity": false,
            "type": "registeredUser",
            "email": "test@test.com",
            "history": {
                "createdAt": "2019-11-18",
                "modifiedAt": "2019-11-18",
                "passwordModifiedAt": "2019-10-15",
                "paymentAccountEnrolledAt": "2019-11-18"
            }
        },
        "transaction": {
            "reorder": true,
            "preOrderDate": "2019-11-18",
            "firstName": "John",
            "lastName": "Appleseed",
            "phoneNumber": "00000000000",
            "history": {
                "attemptsLastDay": 2,
                "attemptsLastYear": 6,
                "completedLastSixMonths": 6,
                "addCardsLastDay": 5,
                "shippingAddressFirstUsedAt": "2018-09-18"
            },
            "giftCardsPurchase": {
                "totalValue": {
                    "currency": "GBP",
                    "amount": 10
                },
                "quantity": 4
            }
        },
        "shipping": {
            "nameMatchesAccountName": false,
            "method": "verifiedAddress",
            "timeFrame": "nextDay",
            "email": "test@test.com"
        }
    }
}

Token
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        }
    },
    "deviceData": {
        "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
        "acceptHeader": "text/html",
        "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    },
    "challenge": {
        "windowSize": "600x400",
        "preference": "noPreference",
        "returnUrl": "http://returnUrl.example.com"
    },
    "riskData": {
        "account": {
            "previousSuspiciousActivity": false,
            "type": "registeredUser",
            "email": "test@test.com",
            "history": {
                "createdAt": "2019-11-18",
                "modifiedAt": "2019-11-18",
                "passwordModifiedAt": "2019-10-15",
                "paymentAccountEnrolledAt": "2019-11-18"
            }
        },
        "transaction": {
            "reorder": true,
            "preOrderDate": "2019-11-18",
            "firstName": "John",
            "lastName": "Appleseed",
            "phoneNumber": "00000000000",
            "history": {
                "attemptsLastDay": 2,
                "attemptsLastYear": 6,
                "completedLastSixMonths": 6,
                "addCardsLastDay": 5,
                "shippingAddressFirstUsedAt": "2018-09-18"
            },
            "giftCardsPurchase": {
                "totalValue": {
                    "currency": "GBP",
                    "amount": 10
                },
                "quantity": 4
            }
        },
        "shipping": {
            "nameMatchesAccountName": false,
            "method": "verifiedAddress",
            "timeFrame": "nextDay",
            "email": "test@test.com"
        }
    }
}

### Risk data

To reduce the chance of a `challenged` outcome we recommend that you include additional `riskData` in your [authentication request](#authentication-example-request).

The additional `riskData` is used by your customer's card issuer. It decides if your authentication request requires a challenge or can be authenticated successfully without a challenge (also known as frictionless authentication).

There are three `riskData` objects you can include in your request:

details
summary
Account
Descriptions of your additional Account `riskData` parameters:

| Parameter | Mandatory | Description |
|  --- | --- | --- |
| `account` | ❌ | Object containing all customer account related risk data. |
| `account.previousSuspiciousActivity` | ❌ | truefalse |
| `account.type` | ❌ | `guestUser` - Order placed without full merchant account registration (no password) `registeredUser`- Order placed with full merchant account registration (password entered)`federatedAccount` - Using a Federated ID `issuerCredentials`- Using issuer credentials`thirdPartyAuthentication` - Using third party authentication`fidoAuthenticator` - FIDO authentication standard |
| `account.email` | **EMVco Required** | The customer's email address. We recommend you provide at least one of either `transaction.phoneNumber` or `account.email`. |
| `account.history.createdAt` | ❌ | When the account was created. |
| `account.history.modifiedAt` | ❌ | When the account was last modified. |
| `account.history.passwordModifiedAt` | ❌ | When the account password was last changed. |
| `account.history.paymentAccountEnrolledAt` | ❌ | Date the payment account was added to the cardholder account. |


details
summary
Transaction
Descriptions of your additional Transaction `riskData` parameters:

| Parameter | Mandatory | Description |
|  --- | --- | --- |
| `transaction` | ❌ | Object containing all customer transaction related risk data. |
| `transaction.reorder` | ❌ | Repeat of a previous order :truefalse |
| `transaction.preOrderDate` | ❌ | Expected date that a pre-ordered purchase will be available. |
| `transaction.firstName` | ❌ | Customer's first name. |
| `transaction.lastName` | ❌ | Customer's last name. |
| `transaction.phoneNumber` | **EMVco Required** | Customer's phone number. We recommend you provide at least one of either `transaction.phoneNumber` or `account.email`. |
| `transaction.history` | ❌ | Object containing details of the last transaction. |
| `history.attemptsLastDay` | ❌ | Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours. |
| `history.attemptsLastYear` | ❌ | Number of transactions (successful or abandoned) for this cardholder account within the last year. |
| `history.completedLastSixMonths` | ❌ | Number of purchases with this cardholder account during the previous six months. |
| `history.addCardsLastDay` | ❌ | Number of attempts to add a card in the last 24hrs. |
| `history.shippingAddressFirstUsedAt` | ❌ | When the shipping address used for the transaction was first used. |
| `transaction.giftCardsPurchase` | ❌ | If the order is being used to purchase a gift card. |
| `giftCardsPurchase.totalValue.currency` | ❌ | The 3 digit currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes). If provided must include `totalValue.amount`. |
| `giftCardsPurchase.totalValue.amount` | ❌ | The amount being placed on the gift card. If provided must include `totalValue.currency`. |
| `giftCardsPurchase.quantity` | ❌ | The number of gift cards being purchased. |


details
summary
Shipping
Descriptions of your additional Shipping `riskData` parameters:

| Parameter | Mandatory | Description |
|  --- | --- | --- |
| `shipping` | ❌ | Object containing all data related to how the order will be shipped. |
| `shipping.nameMatchesAccountName` | ❌ | Cardholder name on account is identical to the shipping name: truefalse |
| `shipping.method` | ❌ | `billingAddress` - Ship to customers billing address`verifiedAddress`- Ship to another verified address on file with merchant`otherAddress`- Ship to address that is different than billing address`store` - Ship to store (store address should be populated on request)`digital` - Digital goods`unshippedTickets`  - Travel and event tickets, not shipped`other` - Other |
| `shipping.timeFrame` | ❌ | `electronic``sameDay``nextDay``twoDaysPlus` |
| `shipping.email` | ❌ | The email address used for an electronic delivery. |


## Authentication responses

The response contains the outcome of your authentication request.

Authenticated
{
    "outcome": "authenticated",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
Authentication Failed
{
    "outcome": "authenticationFailed",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "eci": "07",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    },
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}
Challenged
{
    "outcome": "challenged",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0"
    },
    "challenge": {
        "reference": "123456789",
        "url": "https://ChallengePageUrl.example.com",
        "jwt": "VGhpcyBpcyBhIGJhc2UgNjQgZW5jb2RlZCBleGFtcGxlIG9mIGEgM0RTICJwYXlsb2FkIg=="
    },
    "_links": {
        "3ds:verify": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/verification"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}
Not Enrolled
{
    "outcome": "notEnrolled",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "1.0.2",
        "eci": "06"
    }
}

Unavailable
{
    "outcome": "unavailable",
    "transactionReference": "unique-transactionReference",
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}
Bypassed
{
    "outcome": "bypassed",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "eci": "07",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
| Parameter | Description |
|  --- | --- |
| `outcome` | The outcome of your authentication request.`authenticated` - Successful frictionless authentication.`authenticationFailed` - Your customer could not be authenticated successfully.`challenged` - Authentication details should not be trusted. [Challenge](/products/3ds/v1/challenge-verification) required.`notEnrolled` - Issuer not enrolled for 3DS.`unavailable` - Authentication unavailable.`bypassed` - 3DS check is bypassed. Returned if 3DS premium is enabled or when there is a timeout connecting to the 3DS directory server.To understand more about the `outcomes` and how to reproduce them, see [3DS testing](/products/3ds/v1/testing#authentication). |
| `challenge.reference`  | This links the authentication response to the subsequent challenge form and verification request. |
| `challenge.url` | POST action on the challenge form. Used to redirect to the issuers challenge page as part of the challenge form. Do not use the `challengeUrl`  as the source(src) in the iframe. |
| `challenge.jwt` | A digitally signed token that contains additional details, such as the URL to return to after the challenge screen. |
| `authentication.version` | The version of 3DS used to process the transaction.  Required for Mastercard's Identity Check transactions in Authorization. |
| `authentication.authenticationValue` | A cryptographic value that provides evidence of the outcome of a 3DS verification.Visa - Cardholder Authentication Verification Value (CAVV)Mastercard - Universal Cardholder Authentication Field (UCAF)  Used when [authorizing a payment](/products/card-payments/v6/authorize-a-payment). |
| `authentication.eci` | Electronic Commerce Indicator (ECI).Indicates the outcome of the 3DS authentication.02 or 05 - Fully Authenticated Transaction01 or 06 - Attempted Authentication Transaction00 or 07 - Non 3-D Secure TransactionMastercard - 02, 01, 00Visa - 05, 06, 07Amex - 05, 06, 07JCB - 05, 06, 07Diners - 05, 06, 07 You will need to use this when you are [authorizing a payment](/products/card-payments/v6/authorize-a-payment). |
| `authentication.transactionId` | A transaction identifier.If provided, you should use it as part of your [payment authorization](/products/card-payments/v6/authorize-a-payment). If the `authentication.value` has a major version of:`1` - value returned known as `xid``2` - value returned known as `dsTransactionId` |


**Next steps**

[Challenge](/products/3ds/v1/challenge-verification)[Take a payment](/products/card-payments/v6/authorize-a-payment#3ds)
[3DS testing](/products/3ds/v1/testing)