We have released a new version. Documentation for our latest version can be found here.

Last Updated: 17 January 2024 | Change Log

Challenge Display & 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 do 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="">

  <!-- Set the JWT to the 'challenge.jwt' value from the authentication response. JWT can be viewed using: -->

    <input type = "hidden" name= "JWT" value= "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1NDQzOGIzYS1iYjUzLTEyY2QtODY0My0xNTM2YmU3M2ZmMzUiLCJpYXQiOiIzODU2NzI5NDgyIiwiaXNzIjoiNWJkOWUwZTQ0NDRkY2UxNTM0MjhjOTQwIiwiT3JnVW5pdElkIjoiNWJkOWI1NWU0NDQ0NzYxYWMwYWYxYzgwIiwiUmV0dXJuVXJsIjoiaHR0cDovL21lcmNoYW50LmV4YW1wbGUuY29tL3RocmVlZHNjaGFsbGVuZ2Vjb21wbGV0ZSIsIlBheWxvYWQiOnsiQUNTVXJsIjoiaHR0cHM6Ly9hY3MuZXhhbXBsZS5jb20vM2RzMi9jaGFsbGVuZ2U_aWQ9MTIzNDU2Nzg5IiwiUGF5bG9hZCI6IlZHaHBjeUJwY3lCaElHSmhjMlVnTmpRZ1pXNWpiMlJsWkNCbGVHRnRjR3hsSUc5bUlHRWdNMFJUSUNKd1lYbHNiMkZrSWc9PSIsIlRyYW5zYWN0aW9uSWQiOiJzUk1QV0NRb1FyRWlWeGVoVG51MCJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlfQ.3Dqjr5MuEC9AG7uvsJCft94-d70NmgR94zIeru8fAYE" />

    <!-- Extra field for you to pass data in to the challenge that will be included in the post back to the return URL after challenge complete -->
    <input type="hidden" name="MD" value="merchantSessionId=1234567890" />


Your customer is redirected back to your site after the challenge form is complete using the challenge.returnUrl value specified in your authentication request. As form data you will also receive TransactionId=123456789 that will be the same value as challenge.reference and MD= with any value you passed over from the challenge form.


Once the challenge form has been completed, a verification request needs to be made 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


Verification request body:

    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    "challenge": {
        "reference": "123456789"

Verification responses

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

  1. Authenticated
  2. Authentication Failed
  3. Signature Failed
  4. Unavailable
  5. Bypassed
    "outcome": "authenticated",
    "transactionReference": "unique-transactionReference",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"

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.

authentication.versionThe version of 3DS used to process the transaction.
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 when authorizing 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 are authorizing a payment.
authentication.transactionIdA transaction identifier.
If provided, you should use it as part of your payment authorization.
If the authentication.value has a major version of:
  • 1 - value returned known as xid
  • 2 - value returned known as dsTransactionId

Next steps

Take a payment
3DS testing