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

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

# Challenge Display and Verification

You must have a self submitting form within an iframe to display the issuers challenge screen.

To display the issuers challenge screen within the iframe, use the following parameters from the authentication response:

- `challenge.reference`
- `challenge.url`
- `challenge.jwt`


The content within the iframe is from the issuing bank. The bank will do an identity check on your customer.

## Challenge form

Here's an example of how you would set-up the challenge form in an iframe.


```
<iframe height= "400" width= "390" > //Default 3DS1 challenge window size

  <!-- Set the action to the value in the 'challenge.url' from the authentication response -->
  <form name= "challengeForm" method= "POST" action="https://challengeUrl.example.com">

  <!-- Set the JWT to the 'challenge.jwt' value from the authentication response. JWT can be viewed using: https://jwt.io -->

    <input type = "hidden" name= "JWT" value= "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1NDQzOGIzYS1iYjUzLTEyY2QtODY0My0xNTM2YmU3M2ZmMzUiLCJpYXQiOiIzODU2NzI5NDgyIiwiaXNzIjoiNWJkOWUwZTQ0NDRkY2UxNTM0MjhjOTQwIiwiT3JnVW5pdElkIjoiNWJkOWI1NWU0NDQ0NzYxYWMwYWYxYzgwIiwiUmV0dXJuVXJsIjoiaHR0cDovL21lcmNoYW50LmV4YW1wbGUuY29tL3RocmVlZHNjaGFsbGVuZ2Vjb21wbGV0ZSIsIlBheWxvYWQiOnsiQUNTVXJsIjoiaHR0cHM6Ly9hY3MuZXhhbXBsZS5jb20vM2RzMi9jaGFsbGVuZ2U_aWQ9MTIzNDU2Nzg5IiwiUGF5bG9hZCI6IlZHaHBjeUJwY3lCaElHSmhjMlVnTmpRZ1pXNWpiMlJsWkNCbGVHRnRjR3hsSUc5bUlHRWdNMFJUSUNKd1lYbHNiMkZrSWc9PSIsIlRyYW5zYWN0aW9uSWQiOiJzUk1QV0NRb1FyRWlWeGVoVG51MCJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlfQ.3Dqjr5MuEC9AG7uvsJCft94-d70NmgR94zIeru8fAYE" />

    <!-- Extra field for you to pass data in to the challenge that will be included in the post back to the return URL after challenge complete -->
    <input type="hidden" name="MD" value="merchantSessionId=1234567890" />
  </form>

</iframe>
```

Your customer is redirected back to your site after the challenge form is complete using the `challenge.returnUrl` value specified in your [authentication request](/access/products/3ds/v1/authentication). As form data you will also receive `TransactionId=123456789` that will be the same value as `challenge.reference` and `MD=` with any value you passed over from the challenge form.

# Verification

Once the challenge form has been completed, a verification request needs to be made to verify the result of the challenge form.

POST your verification request to our `3ds:verify` action link received in your authentication response if your outcome is `challenged`.

## Verification example request

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

Verification request body:


```json
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "challenge": {
        "reference": "123456789"
    }
}
```

## Verification responses

Here are examples of the verification responses you would get. To understand what these outcomes mean and how to reproduce them for testing purposes see [3DS testing](/access/products/3ds/v1/testing)

Authenticated

```json
{
    "outcome": "authenticated",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
```

Authentication Failed

```json
{
    "outcome": "authenticationFailed",
    "transactionReference": "unique-transactionReference",
    "authentication": {
      "version": "1.0.2",
      "eci": "00",
      "transactionId": "N+en2I5+ZK/kQqk69wXdI8XIPg8="
    },
    "_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"
        }]
    }
}
```

Signature Failed

```json
{
    "outcome": "signatureFailed",
    "transactionReference": "unique-transactionReference",
    "authentication": {
      "version": "1.0.2",
      "eci": "02"
    },
    "_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"
        }]
    }
}
```

Unavailable

```json
{
    "outcome": "unavailable",
    "transactionReference": "unique-transactionReference",
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "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"
        }]
    }
}
```

Bypassed

```json
{
    "outcome": "bypassed",
    "transactionReference": "6032c024-8d33-4e89-98e9-a944f66c3906",
    "authentication": {
        "version": "2.1.0",
        "eci": "00",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
```

Warning
You cannot re-use the `authenticationValue` in multiple authorization requests. Re-using the `authenticationValue` in this way will result in issuer declines and may incur fees.

Use the values: `version`, `authenticationValue`, `eci`, `transactionId` from the request when [authorizing a payment](/access/products/card-payments/v6/authorize-a-payment). The values prove that the verification was successful, and that the fraud liability has shifted to the issuer.

| Parameter | Description |
|  --- | --- |
| `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](/access/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](/access/products/card-payments/v6/authorize-a-payment). |
| `authentication.transactionId` | A transaction identifier.If provided, you should use it as part of your [payment authorization](/access/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**

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