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/)

# 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 perform 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" />

    <!-- Optional field (max 1024 characters) for you to pass url parameters in the challenge form that will be included/echoed in the response url (`challenge.returnUrl`) after the challenge is complete -->
    <input type="hidden" name="MD" value="merchantSessionId=1234567890" />
  </form>

  <script>
    window.onload = function() {
      // Auto submit form on page load
      document.getElementById('challengeForm').submit();
    }
  </script>

</iframe>
```

The size you specify for the iframe depends on whether you have provided a `challenge.windowSize` in the [authentication request](/products/3ds/v2/web/authentication) and the `authentication.version` returned in the authentication response:

For an `authentication.version` value of:

* `1.x.x` - the size must be 390x400
* `2.x.x` - match the value supplied in the [authentication request](/products/3ds/v2/web/authentication). If not supplied use the default 390x400.


Note
If you get a 400 response on POST of the challenge form ensure:The JWT has not expired (10 minutes)Element/form data names are upper case e.g. `JWT` as shown in the example

Once the challenge is complete there is a redirect back to the `challenge.returnUrl` provided in the [authentication request](/products/3ds/v2/web/authentication). As form data you will also receive `TransactionId=123456789` that will be the same value as `challenge.reference`. If included as part of your challenge form the `MD=` value will be included as a parameter at the end of the `challenge.returnUrl`.

# Verification

Once the challenge form has been completed, you must make a verification request 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-bsh.securedataplatform.com/verifications/customers/3ds/verification`

Verification request body:

{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "challenge": {
        "reference": "123456789"
    }
}
## Verification responses

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

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

Authentication Failed
{
    "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-bsh.securedataplatform.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}

Signature Failed
{
    "outcome": "signatureFailed",
    "transactionReference": "unique-transactionReference",
    "authentication": {
      "version": "1.0.2",
      "eci": "02"
    },
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}

Unavailable
{
    "outcome": "unavailable",
    "transactionReference": "unique-transactionReference",
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/verifications/customers/3ds/authentication"
        },
        "3ds:verify": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/verifications/customers/3ds/verification"
        },
        "curies": [{
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}
Bypassed
{
  "outcome": "bypassed",
  "transactionReference": "6032c024-8d33-4e89-98e9-a944f66c3906",
  "authentication": {
    "version": "2.1.0",
    "eci": "00",
    "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
  }
}

Use the values: `version`, `authenticationValue`, `eci`, `transactionId` from the request when [authorizing a payment](/products/card-payments/v6/authorize-a-payment#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](/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.version` has a major version of:`1` - value returned known as `xid``2` - value returned known as `dsTransactionId` |


**Next steps**

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