Authentication

API v3

Last updated January 2023

POST your authentication request to the 3ds:authenticate action link. Your authentication request sends order and risk data used to decide if achallengeis required.

Important: You should only request the authentication API from your backend system. You should not call it directly from the mobile application using the Access credentials.

Authentication example request

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

Authentication request body:

Copied!

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
      "entity": "MindPalaceLtd",
      "overrideName": "The Baskerville Animal Sanctuary"
  },
  "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",
          "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)",
    "browserLanguage": "en-GB",
    "ipAddress": "192.0.0.0"
  },
  "challenge": {
    "windowSize": "600x400",
    "preference": "noPreference",
    "returnUrl": "http://payment.example.com"
  },
  "riskData": {
    "account": {
      "previousSuspiciousActivity": false,
      "type": "registeredUser",
      "email": "sherlock.holmes@example.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": "Sherlock",
      "lastName": "Holmes",
      "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": "sherlock.holmes@example.com",
      "address": {
        "address1": "Disneyland",
        "address2": "Disneyland Drive",
        "address3": "Adventure Park",
        "postalCode": "DL1 2CA",
        "city": "Anaheim",
        "stateCode": "CA",
        "countryCode": "GB",
        "phoneNumber": "01911234321"
      }
    }
  }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "overrideName": "The Baskerville Animal Sanctuary"
    },
    "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)",
        "browserLanguage": "en-GB",
        "ipAddress": "192.0.0.0"
    },
    "challenge": {
        "windowSize": "600x400",
        "preference": "noPreference",
        "returnUrl": "http://payment.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": "sherlock.holmes@example.com",
            "address": {
                "address1": "Disneyland",
                "address2": "Disneyland Drive",
                "address3": "Adventure Park",
                "postalCode": "DL1 2CA",
                "city": "Anaheim",
                "stateCode": "CA",
                "countryCode": "GB",
                "phoneNumber": "01911234321"
            }
        }
    }
}

How much data to provide

Thedevice dataand 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 will vary by issuer but supplying more data will increase the chances of the outcome being frictionless (without achallenge) and for some issuers fail the authentication entirely.

Optional data we recommend including as a minimum:

paymentInstrument.billingAddress - including sub values
deviceData.collectionReference
deviceData.browserLanguage
deviceData.ipAddress
riskData.account.email
riskData.transaction.firstName
riskData.transaction.lastName
riskData.transaction.phoneNumber

For details see the tables below where they are clearly marked as recommended.

Note: 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 Descriptions

For the API schema seeAPI reference.

Parameter	Mandatory	Description
`transactionReference`		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.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` Seeauthentication(card)above `type` : `card/tokenized` Seeauthentication(token)above
`paymentInstrument.cardHolderName`		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`	Recommended	An object containing the billing address information. If included, you must send at least: `address1` `city` `countryCode` `postalCode` `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 addresses
`instruction.value`		An object that contains information about the value of the authentication.
`value.currency`		The three digit currency code. See list ofsupported currencies.
`value.amount`		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 ourcurrency table. 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.
`deviceData.acceptHeader`		Used by the issuer to check if the customer's browser is compatible with the issuer challenge display.
`deviceData.userAgentHeader`		Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform toRFC 7321 E.g. `Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)`
`deviceData.collectionReference`	Recommended	For web this is the `session Id` in the postMessage response from theDevice Data Collection form For iOS/Android SDK this is the `consumerSessionId` returned as part ofSDK and Device data initialization
`deviceData.browserLanguage`	Recommended	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`	Recommended	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
`challenge.windowSize`		Specify the challenge window size (width x height) that the issuer should use. This is to better tailor the experience to the customers device. `250x400` `390x400` (default) `600x400` `500x600` `fullpage` - expand to fill viewport Note: We recommend a minimum of 400x500 as not all issuers conform strictly.
`challenge.preference`		`noPreference` - default `noChallengeRequested` - prefer no challenge performed `challengeRequested` - prefer challenge is performed `challengeMandated` - local or region mandates meaning a challenge must be performed Important: You should use `challengeMandated` in the authentication request as part of the first CIT payment in an MIT series. We strongly recommend setting this when first storing cards in general (e.g. first payment where a token is stored or independently "adding a card" to an account). 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`		Once the customer completes thechallengepage the issuer redirects/posts to the `returnUrl` in order for you to resume the session. It must be the full URL path.

Risk data

To reduce the chance of a challenged outcome, we recommend that you include additional riskData in yourauthentication request.

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

Account

Parameter	Mandatory	Description
`account`		Object containing all customer account related risk data.
`account.previousSuspiciousActivity`		true false
`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`	Recommended	The customer's email address.
`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.

Transaction

Parameter	Mandatory	Description
`transaction`		Object containing all customer transaction related risk data.
`transaction.reorder`		Repeat of a previous order : true false
`transaction.preOrderDate`		Expected date that a pre-ordered purchase will be available.
`transaction.firstName`	Recommended	Customer's first name.
`transaction.lastName`	Recommended	Customer's last name.
`transaction.phoneNumber`	Recommended	Customer's phone number.
`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 customer 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 three digit currency code. See list ofsupported currencies. 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.

Shipping

Parameter	Mandatory	Description
`shipping`		Object containing all data related to how the order will be shipped.
`shipping.nameMatchesAccountName`		Customer name on account is identical to the shipping name: true false
`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.
`shipping.address`		An object containing the shippping address information. If included, you must send at least: `address1` `city` `countryCode` `postalCode`

Authentication responses

Best Practice: Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

The response contains the outcome of your authentication request.

Copied!

{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}

{
    "outcome": "authenticationFailed",
    "transactionReference": "Memory265-13/08/1876",
    "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"
        }]
    }
}

{
    "outcome": "challenged",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0"
    },
    "challenge": {
        "reference": "123456789",
        "url": "https://ChallengePageUrl.example.com",
        "jwt": "VGhpcyBpcyBhIGJhc2UgNjQgZW5jb2RlZCBleGFtcGxlIG9mIGEgM0RTICJwYXlsb2FkIg==",
        "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVE"
    },
    "_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"
        }]
    }
}

{
    "outcome": "notEnrolled",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "1.0.2",
        "eci": "06"
    }
}

{
    "outcome": "unavailable",
    "transactionReference": "Memory265-13/08/1876",
    "_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"
        }]
    }
}

{
    "outcome": "bypassed",
    "transactionReference": "Memory265-13/08/1876",
    "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.Challengerequired. `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, see3DS testing.
`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. Expires in 10 minutes for both Try and Production.
`challenge.payload`	JSON container with extra data required for the challenge. Note: This is only for use with the native mobile App SDK's. It is not required for the web integration.
`authentication.version`	The version of 3DS used to process the transaction. Note: 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 whenauthorizing a payment.
`authentication.eci`	Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication. 02 or 05 - Fully Authenticated Transaction 01 or 06 - Attempted Authentication Transaction 00 or 07 - Non 3-D Secure Transaction Mastercard - 02, 01, 00 Visa - 05, 06, 07 Amex - 05, 06, 07 JCB - 05, 06, 07 Diners - 05, 06, 07 You will need to use this when you areauthorizing a payment.
`authentication.transactionId`	A transaction identifier. If provided, you should use it as part of yourpayment authorization. If the `authentication.version` has a major version of: `1` - value returned known as `xid` `2` - value returned known as `dsTransactionId`

Note: In case of an error, you can get further information in ourerror reference.

Next steps

Challenge
Take a payment

Authentication

Authentication example request

How much data to provide

Parameter Descriptions

Risk data

Account

Transaction

Shipping

Authentication responses

Searching accross the entire site

Filter by product

Filter by product Searching across the entire site

Authentication

Authentication example request

How much data to provide

Parameter Descriptions

Risk data

Account

Transaction

Shipping

Authentication responses

Searching accross the entire site

Filter by product

Filter by product Searching across the entire site

​