On This Page
Simple Order API

Building the Iframe Parameters

The iframe that the merchant displays 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 the merchant 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. The size of the challenge window is managed by the merchant to ensure that the challenge window matches with the presentation screen provided by the merchant. The merchant chooses the iframe parameters and passes 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"
}