Last Updated: 08 October 2024 | Change Log

Challenge display and verification

Use 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 the authentication 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.

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.

iframe for challenge form

<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 the authentication request.

Create and host the page that POSTs the Challenge form.

iframe for challenge form

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

Test challenge form

The form below allows you to submit the 3DS challenge details provided in the API response and display the issuer challenge. This is useful if using tools such as postman/insomnia to test your integration.

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 the authentication 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:

TransactionId - same value as challenge.reference from the authentication response and used in the verification request.
MD - If included as part of the challenge form.

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:

application/vnd.worldpay.verifications.customers-v3.hal+json

An example of a verification request to return the 3DS authentication data

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "challenge": {
    "reference": "1xoKSqTvmLvhRYBsaE60"
  }
}

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 see 3DS testing.

authenticated

{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069"
    }
}

authenticated - Cartes Bancaires

{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
        "eci": "05",
        "transactionId": "1be85590-d6f9-4a0b-93c9-3a7188d9a463",
        "cryptogramAlgorithm": 1,
        "challengePreference": "challengeMandated",
        "authenticationFlow": "challenge",
        "brand": "cartesBancaires",
        "acsTransactionId": "d9eb0787-94cc-485f-97f3-93403141a3af"
    }
}

Apply the details (such as eci, version, authenticationValue, transactionId) required by Card Payments in the authorization request. See Testing for details.

versionstring[ 1 .. 10 ] characters

The version of 3DS used to process the transaction.

ecistring[ 1 .. 2 ] characters

Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication.

ECI	Meaning
02 or 05	Fully Authenticated Transaction
01 or 06	Attempted Authentication Transaction
00 or 07	Non 3-D Secure Transaction

Scheme	Value
Mastercard	02, 01, 00
Visa	05, 06, 07
Amex	05, 06, 07
JCB	05, 06, 07
Diners	05, 06, 07

authenticationValuestring[ 1 .. 64 ] characters

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)

transactionIdstring[ 1 .. 64 ] characters

Directory server transaction Id, if provided should be used in the payment authorization authentication object

cryptogramAlgorithmstring[ 1 .. 99999 ] characters

Indicates the algorithm used to generate the cryptogram. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

challengePreferencestring[ 1 .. 64 ] characters

Indicates the preferred challenge behavior. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

noPrefrence
noChallengeRequested
challengeRequested
challengeMandated

authenticationFlowstring[ 1 .. 64 ] characters

Indicates which flow the customer has been directed to. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

Enum"challenge""frictionless"

statusReasonstring[ 1 .. 2 ] characters

Provides further information relating to the outcome of the authentication. Returned for failed authentications only. Returned for Cartes Bancaires authentications only.

cancellationIndicatorstring[ 0 .. 2 ] characters

An indicator as to why the authentication was cancelled. Returned for Cartes Bancaires authentications only.

01 - Cardholder selected cancel
02 - Reserved for future use
03 - Authentication timed out
04 and 05 - Authentication timed out at ACS provider
06 - Transaction error
07 - Unknown
08 - Transaction timed out at SDK

networkScorestring[ 0 .. 2 ] characters

The global score calculated by the Cartes Bancaires scoring platform. Returned for Cartes Bancaires authentications only.

brandstring[ 0 .. 64 ] characters

The card brand used in the authentication. Returned for Cartes Bancaires authentications only and must be applied in the following authorization.

Next steps

Take a payment
Testing