Last Updated: 08 October 2024 | Change Log

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 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. If not supplied use the default 390x400.

Once the challenge is complete there is a redirect back to the challenge.returnUrl provided in the authentication request. 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.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.

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

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

Next steps

Take a payment
3DS testing