Menu

Challenge display

API v3
Last updated January 2023
Change log

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 performs an identity check on your customer.

Optional MD field

Pass data specific to your checkout session and it will be echoed back in the challenge.returnUrl originally provided in theauthentication request. This could for example be a checkout sessionId. Any value provided must be URL encoded with a maximum of 1024 characters.

Challenge form

Once you have the JWT and URL you can create and submit the Challenge form.

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

  1. Create an iframe and set the src attribute with the URL of the page that will POST the Challenge form. This URL should contain in query string parameters the challenge.jwt, challenge.url and optionally MD as those will be used in the Challenge form.

    Copied!
    <iframe height= "400" width= "390" src="replace-this-with-the-url-of-your-page-that-posts-the-challenge-form"></iframe>

    The size you specify for the iframe depends on whether you have provided a challenge.windowSize in theauthentication requestand the authentication.version returned in the authentication response:

    For an authentication.version value of 2.x.x, match the value supplied in theauthentication request. If not supplied use the default 400x500.

  2. Create and host the page that POSTs the Challenge form.

    Copied!
    <html>
<head>
</head>
<body>

  <!-- Using your preferred programming language, set the 'action' attribute with the value of the query string parameter containing the 'challenge.url' from the authentication response -->
  <form id="challengeForm" method= "POST" action="https://challengeUrl.example.com">

    <!-- Using your preferred programming language, set the 'value' attribute with the value of the query string parameter containing the 'challenge.jwt' from the authentication response -->
    <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>

</body>
</html>

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

Challenge returnUrl

Once the issuer challenge is complete there is a POST to the challenge.returnUrl (you provide in theauthentication request). This should go to your backend where you can retrieve any of the form data, initiate the verification request and display a page in the iframe depending on the outcome in the verification response.

Form data in returnUrl POST:

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.com/verifications/customers/3ds/verification

Verification request body:

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "challenge": {
        "reference": "123456789"
    }
}

Verification 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.

Here are examples of the verification responses you would receive. To understand what these outcomes mean and how to reproduce them for testing purposes see3DS testing.

Copied!
{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069"
    }
}
{
    "outcome": "authenticationFailed",
    "transactionReference": "Memory265-13/08/1876",
    "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"
        }]
    }
}
{
    "outcome": "signatureFailed",
    "transactionReference": "Memory265-13/08/1876",
    "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"
        }]
    }
}
{
    "outcome": "unavailable",
    "transactionReference": "Memory265-13/08/1876",
    "_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"
        }]
    }
}

Use the values: version, authenticationValue, eci, transactionId from the request whenauthorizing a payment. The values prove that the verification was successful, and that the fraud liability has shifted to the issuer.

ParameterDescription
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.version has a major version of:
  • 1 - value returned known as xid
  • 2 - value returned known as dsTransactionId

Next steps

Take a payment
3DS testing