APIs
/
3DS
/
React Native
/
Challenge display and Verification

Last Updated: 22 April 2025 | Change Log

Challenge display and verification

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 display

The challenge display for React Native uses:

  • a WebView
  • a mobile-friendly HTML page
  • a fullscreen iframe, embedded in the mobile-friendly HTML page, used to display the challenge page to the end user
  • a secondary HTML page, loaded via the iframe, and used to kickstart the challenge display
  1. Install and link the React Native WebView component in your application.
# 1. Install dependency
npm install react-native-webview

# 2. Link dependency using your preferred method
react-native link react-native-webview

# 3. Ee-install pods
cd ios
pod install
  1. Add a WebView in your React Native application with the source pointing to the HTML page created in the next step.
React Native
<WebView source={{ uri: 'replace-this-with-the-url-of-the-mobile-friendly-page' }} />
  1. Create and host the mobile-friendly HTML page.
HTML
<html lang="en">
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body style="margin: 0">
</body>
</html>
  1. Add a fullscreen iframe to the HTML page and set the src attribute to the URL of the page that will POST the hallenge form.
HTML
<iframe src="replace-this-with-the-url-of-your-page-that-posts-the-challenge-form"
        width="100%" height="100%"
        style="height: 100%; width: 100%; border-width: 0">
</iframe>
  1. Create and host the secondary HTML page that POSTs the challenge form.
HTML
<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>

In addition, after the challenge is completed, if you wish to relay a message, you have sent by postMessage() to your mobile-friendly page, to the React Native layer:

  1. Use the following JavaScript in your mobile-friendly page to relay the message to React Native.
Javascript
<script language="JavaScript">
window.onmessage = (event) => {
  // Always verify that the message received is from the expected origin
  if (event.origin !== '...') {
    return;
  }

  // the function below uses a tring, so if you wish to send JSON
  // make sure to serialise it using JSON.stringify()
  window.ReactNativeWebView.postMessage(event.data);
};
</script>
  1. Add an event listener for the message event on your WebView.
React Native
<WebView
  source={{ uri: 'replace-this-with-the-url-of-the-mobile-friendly-page' }}
  onMessage={(event) => {
    // extracting data (string) from the event
    console.info(event.nativeEvent.data);
  }}
/>

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.

Full integration example code

# 1. Install dependency
npm install react-native-webview

# 2. Link dependency using your preferred method
react-native link react-native-webview

# 3. Ee-install pods
cd ios
pod install

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:

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

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

{
  "outcome": "authenticated",
  "transactionReference": "Memory265-13/08/1876",
  "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
  "status": "Y",
  "enrolled": "Y",
  "authentication": {
    "version": "2.1.0",
    "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "eci": "05",
    "transactionId": "c5b808e7-1de1-4069"
  }
}

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.

Successful authentication following a challenge

authenticated
  {
      "outcome": "authenticated",
      "transactionReference": "Memory265-13/08/1876",
      "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
      "status": "Y",
      "enrolled": "Y",
      "authentication": {
          "version": "2.1.0",
          "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
          "eci": "05",
          "transactionId": "c5b808e7-1de1-4069"
      }
  }
authenticated - Cartes Bancaires
    "transactionReference": "Memory265-13/08/1876",
    "acsTransactionId": "fe007a6e-315f-4cdf-98ca-28a9e40e3581",
    "status": "Y",
    "enrolled": "Y",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
        "eci": "05",
        "transactionId": "1be85590-d6f9-4a0b-93c9-3a7188d9a463",
        "cryptogramAlgorithm": "1",
        "challengePreference": "challengeMandated",
        "authenticationFlow": "challenge",
        "brand": "cartesBancaires"
    }
}

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

Next steps

Take a payment
Testing