Menu

Important: We have released a new version. Documentation for our latest version can be foundhere.

Authentication

API v1

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

Authentication example request

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

Authentication request body:

Copied!
{
    "transactionReference": "Memory265-13/08/1986",
    "merchant": {
        "entity": "Mind Palace Ltd"
    },
    "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"
    }
}
{
    "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"
    }
}
ParameterMandatoryDescription
transactionReferenceA unique reference for authentication. for example, e-commerce order code.
merchant.entityUsed to route the authentication request in Access Worldpay, created as part of on-boarding.
instructionThe object that contains all the payment information related to the authentication request.
instruction.paymentInstrumentAn object that contains the card details or token location.
paymentInstrument.typeAn identifier for the paymentInstrument being used.

type : card/fronttype : card/tokenized
paymentInstrument.billingAddressAn object containing the billing address information. If included you must send at least:
deviceData.acceptHeaderUsed by the issuer to check if the customer's browser is compatible with the issuer challenge display.
deviceData.userAgentHeaderUsed by the issuer to check the customer's browser and operating system information.
deviceData.collectionReferenceThe session Id in the postMessage response from theDevice Data Collection Formcontains this reference.

Note: If no value is provided the authentication falls back to 3DS1.

challenge.windowSizeSpecify 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 performed

Important:

  • You 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.returnUrlThe path your customer will be returned to after completing the issuerschallenge screen. Must be the full URL path

Optional fields in an Authentication request

Risk data

To reduce the chance of a challenged outcome we recommend that you include additional riskData in yourauthentication 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:

Authentication responses

The response contains the outcome of your authentication request.

Copied!
{
    "outcome": "authenticated",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
{
    "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"
        }]
    }
}
{
    "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"
        }]
    }
}
{
    "outcome": "notEnrolled",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "1.0.2",
        "eci": "06"
    }
}
{
    "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"
        }]
    }
}
{
    "outcome": "bypassed",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "eci": "07",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
ParameterDescription
outcomeThe 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.referenceThis links the authentication response to the subsequent challenge form and verification request.
challenge.urlPOST 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.jwtA digitally signed token that contains additional details, such as the URL to return to after the challenge screen.
authentication.versionThe version of 3DS used to process the transaction.

Note: Required for Mastercard's Identity Check transactions in Authorization.

authentication.authenticationValueA 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.eciElectronic 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.transactionIdA transaction identifier.
If provided, you should use it as part of yourpayment authorization.
If the authentication.value has a major version of:
  • 1 - value returned known as xid
  • 2 - value returned known as dsTransactionId

Next steps


Challenge
Take a payment
3DS testing