Step 4: Step-Up Iframe

Initiate step-up authentication on the front end after you receive the response as discussed in Step 3: Payer Authentication Check Enrollment Service. Note that frictionless authentication does not require this step-up iframe step. This step is only for step-up authentication when the issuing bank wants to challenge the cardholder.
When a challenge is needed to prove a customer's identity, a JSON Web Token is returned to you that contains a step-up URL. You open an iframe where the access token to the step-up URL (also known as the endpoint) is posted. The iframe must be sized appropriately to enable the cardholder to complete the challenge. The iframe manages customer interaction with the card-issuing bank’s access control server. The bank asks the customer to provide identifying information. Once the customer completes the challenge, the process moves to validating the information that the customer sent.

Figure:

Process Flow for Step-Up Authentication
Process Flow Diagram for Step-up Authentication

Best Practices

These practices should be followed for this step to achieve optimal performance and to minimize potential operating issues.
  • When a transaction requires a challenge, according to EMVCo protocol, the challenge must be issued within 30 seconds of the Enrollment Check response. When more than 30 seconds elapses, the ACS times out.

Building the Iframe Parameters

The iframe that you display should be sized to enable the customer bank to exchange authentication information between itself and the customer. Because a bank can use various methods to authenticate, the iframe has four size options. The bank will request that you ensure that the iframe size provides room to display the bank logo and the card network being used, the amount of the transaction, and a brief explanation of what the customer needs to do. You manage the size of the challenge window to ensure that the challenge window matches with your presentation screen. You choose the iframe parameters and pass the window size to the issuer.
  • Use the JWT POST Parameter value from the
    payerAuthEnrollReply_accessToken
     response field and do a form POST within the iframe to the StepUpUrl value that is passed by the
    payerAuthEnrollReply_stepUpUrl
     response field.
  • MD POST Parameter: Merchant-defined data returned in the response. This field is optional.
  • Iframe height and width: EMV 3-D Secure 2.x offers multiple size options:
    • Use the
      payerAuthEnrollService_acsWindowSize
       request field to request a specific window size.
    • Use the
      payerAuthEnrollReply_paReq
       response field to determine iframe dimensions by Base64 decoding the string and cross-referencing a Challenge Window Size value with its corresponding size.
This table lists the possible values for iframe size and the sizes associated with the value.
Challenge Window Size Value and Corresponding Size
Challenge Window Size Value
Step-Up Iframe Dimensions (Width x Height in pixels)
01
250 x 400
02
390 x 400
03
500 x 600
04
600 x 400
05
Full screen
This is an example for the decoded value.
Challenge Window Size Decoded Value
{
    "messageType":"CReq","messageVersion":"2.2.0",
    "threeDSServerTransID":"c4b911d6-1f5c-40a4-bc2b-51986a98f991",
    "acsTransID":"47956453-b477-4f02-a9ef-0ec3f9f779b3",
    "challengeWindowSize":"02"
}
Step 4: Step-Up Iframe

Creating the Iframe

Create an iframe that is the same size as the Challenge Window Size to send a POST request to the step-up URL. Study this example.
Send a POST Request to the Step-Up URL
<iframe name=”step-up-iframe" height="400" width="400"></iframe>
<form id="step-up-form" target=”step-up-iframe" method="post" action=" https://centinelapistag. cardinalcommerce.com/V2/Cruise/StepUp"> <input type="hidden" name="JWT" value="eyJhbGciOiJIUz I1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmNmFmMTRmOS04YWRjLTRiNzktOGVkYS04YWVlMTI2NTkzZTEiLCJp YXQiOjE1OTYwNTEyNzYsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5NjA1NDg3NiwiT3Jn VW5pdElkIjoiNTVlZjNmNTZmNzIzYWE0MzFjOTlkNTRiIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBt ZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2 FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3 aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUpsTkdKaVpqazNNeTFqTW1FeUxUUTNOREF0T1RWak5 DMWpNVGhoTVRNeE16TmlPRFFpTENKaFkzTlVjbUZ1YzBsRUlqb2lNVGMzT0RFM016SXROREk1TVMwME1HUmlMVG xoTkRndE1ESm1OREpoTlRZd1lqYzVJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcm Fuc2FjdGlvbklkIjoiQnh5a0hYVEp4M1JuNHBGWnF1bjAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0 dXJuVXJsIjoiaHR0cHM6Ly9taWNoYWVsdGF5bG9yLmlvL2N5YnMvc3RvcmVEZW1vL3B1YmxpYy9saXN0ZW5lci5 weSJ9.H8j-VYCJK_7ZEHxGz82_IwZGKBODzPaceJNNC99xZRo" /> <input type="hidden" name="MD" value="optionally_include_custom_data_that_will_be_returned_as_is”/> </form>
Step 4: Step-Up Iframe

Invoking the Iframe

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body>
 tag as shown in the example below. The JavaScript invokes the iframe form POST automatically when the window loads. While you can submit the form at a different time, you must submit the form before requesting the validation service.
<script>
window.onload = function() {   
    var stepUpForm = document.querySelector('#step-up-form');
    if(stepUpForm) // Step-Up form exists
    stepUpForm.submit();
}
</script>
Step 4: Step-Up Iframe

Receiving the Step-Up Results

After the customer interacts with the issuing bank, the customer is returned to the
payerAuthEnrollService_returnURL
 within the iframe as specified in Step 3: Payer Authentication Check Enrollment Service. The payload sent to the return URL is URL-encoded and Base64-encoded (see the example below). Since you host the return URL, you can then close the iframe after redirection.
The response sent back to the return URL contains these values:
  • Transaction ID: (
    payerAuthEnrollReply_authenticationTransactionID
     response field). This value is used in Step 5: Payer Authentication Validation Service.
  • MD: merchant data returned if present in the POST to step-up URL; otherwise, null.
POST to Return URL
TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=null
Step 4: Step-Up Iframe