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

Last Updated: 18 February 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:

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"
  }
}
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.

Authenticated
description: An example of a verification request to return the 3DS authentication data
value:
  {
      "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
{
    "outcome": "authenticated",
    "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.

versionstring[ 1 .. 10 ] characters

The version of 3DS used to process the transaction.

ecistring[ 1 .. 2 ] characters

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

ECIMeaning
02 or 05Fully Authenticated Transaction
01 or 06Attempted Authentication Transaction
00 or 07Non 3-D Secure Transaction
SchemeValue
Mastercard02, 01, 00
Visa05, 06, 07
Amex05, 06, 07
JCB05, 06, 07
Diners05, 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.

  • noPreference
  • noChallengeRequested
  • challengeRequested
  • challengeMandated
  • noChallengeRequestedTRAPerformed
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