Contents x
    Get3DSVersion
    • 23 Dec 2025
    • 7 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Contents

    Get3DSVersion

    • Updated on 23 Dec 2025
    • 7 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Article summary

    This message enables merchants to retrieve the applicable 3DS version for a given card and is intended for use by the following merchant types:

    1. Merchants integrating PayOne Authentication services independently, such as Payment Service Providers (PSPs), who manage the authentication flow as a separate process.

    2. Merchants utilizing PayOne Authorization services (API Payment or API PreAuth), who are required to determine the card’s 3DS version prior to submitting a request to SmartRoute. These merchants must invoke the Get Card 3DS Version API before initiating the payment or pre-authorization flow.

    For merchants in the second category, the following process must be followed:

    • After collecting the card details (card number, expiry date, and cardholder name), and before calling the API Payment or API PreAuth endpoint, the merchant must invoke the Get Card 3DS Version API.

    • The merchant must evaluate the Response.StatusCode returned:

      • If the status code indicates an error (i.e., not 00000), the payment flow cannot proceed. A new request to the Get Card 3DS Version API must be submitted.

      • If the status code is successful (00000) and Response.MethodPostData is empty or not present, the merchant may proceed by calling the API Payment or API PreAuth.

      • If the status code is successful (00000) and Response.MethodPostData is provided, the merchant must render an iframe to POST the Response.MethodPostData to Response.MethodDataURL. The iframe must not remain open for more than 10 seconds. If this duration is exceeded, the merchant should proceed with the subsequent API calls.

    A sample JavaScript implementation is provided below to illustrate this behavior

    ActionScript
    var url = response["methodDataURL"]; // this is from the response of Get Card 3DS Version API call
var threeDSMethodData = response["methodPostData"];// this is from the response of Get Card 3DS Version API call

var ifrm = document.createElement('iframe');
ifrm.setAttribute('id', 'threeDSMethodDataIframe'); // assign an id
ifrm.setAttribute('name', 'threeDSMethodDataIframe'); // assign a name

ifrm.style.width = '0px';
ifrm.style.height = '0px';
ifrm.setAttribute('frameborder', '0');
ifrm.setAttribute('style', 'visibility: hidden; position: absolute; left: 0; top: 0; height:0; width:0; border: none;');

document.body.appendChild(ifrm); // to place at end of document

var html = "<form action = 'MethodDataURL' method='POST' id = 'threeDSMethodDataForm' name = 'threeDSMethodDataForm' target = 'threeDSMethodDataIframe'>";
html += "<input type = 'hidden' name = 'threeDSMethodData' value = '" + threeDSMethodData + "'/>";
html += "<input type = 'hidden' name = 'JWT' value = '" + threeDSMethodData + "'/>";
html += "</form>";

html +=    "<script>document.getElementById('threeDSMethodDataForm').submit();<\/script>";

    Request Parameters

    ParameterDescription
    AuthenticationToken
    required    		AuthenticationToken Value send in request Header.
    • Field Type: Alphanumeric
    • Length: 255
    • Sample Data: 27

    MessageID
    required    		Alphanumeric value representing the action to be called. 

    27 for Get 3DS Version

    • Field Type: Alphanumeric 
    • Length: 2
    • Sample Data: 27
    MerchantID
    required    		Alphanumeric value representing the unique ID of the merchant at SmartRoute, this value is provided by SmartRoute operation team upon merchant enrollment. 
    • Field Type: Alphanumeric 
    • Length: 40
    • Sample Data: MID0001 
    TransactionID
    required

    The Transaction ID generated by the Merchant, it represents a unique identifier for the transaction, and it is alphanumeric. It can’t include special characters neither space.

    • Field Type: Alphanumeric 
    • Length: 40
    • Sample Data: 1440954863817 
    Channel
    required

    The Channel to be used by SmartRoute System. It could be one of the following: 

    • 0 for E-Commerce
    • 1 for IVR
    • 3 for SDK (Mobile)
    • Field Type: Numeric
    • Length: 1
    • Sample Data: 3
    Version
    optional    		A numeric value with (.) separator represents the command's version to be used. If this value is not provided, SmartRoute will consider its default value which is 1.0.  
    • Field Type: Numeric
    • Length: 5
    • Sample Data: 1.0

    CurrencyISOCode 
    required     		The numeric ISO Code for the currency and not the character value.
    • Field Type: Number 
    • Length: 3
    • Sample Data: 840
    Sample ISO Codes values:
    • 840 for US Dollar
    • 400 for JOD
    • 682 for SAR
    • 784 for AED
    CardNumber
    required     		The customer’s card number that will be used in the payment. This parameter is required if the sent PaymentMethod parameter is 1 (Card).
     
    • Field Type: Numeric
    • Length: 19
    • Sample Data: 4111111111111111
    Token
    required    		The token is used in this request; to represent previously used card information. This parameter is a part of the tokenization parameters. For more information, see Tokenization
    • Field Type: Alphanumeric 
    • Length: 64
    • Sample Data: 17b61316feafe09feb806ce33cdbfc85aed1b4173ed604f8fd5fa3cf72a02e27 
    ExpiryDateMonth
    required    		The customer’s card expiry date month digits that will be used in the payment. The format of this parameter should be in the form (MM). This parameter is required if the sent PaymentMethodparameter is 1 (Card).
    • Field Type: Numeric 
    • Length: 2
    • Sample Data: 02 
    ExpiryDateYear
    required 

    The customer’s card expiry date year digits that will be used in the payment. The format of this parameter should be in the form (YY). This parameter is required if the sent PaymentMethod parameter is 1 (Card)

    • Field Type: Numeric
    • Length: 2
    • Sample Data: 17
    PaymentMethod 
    optional

    A numeric value to indicate which payment method will be used. 

    Supported values are:

    1 means a payment using Card.

    9 means a payment using GooglePay

    If not sent then the default value is 1 (Card)
    • Field Type: Numeric 
    • Length: 1
    • Sample Data: 1
    googlePayResponse 
    conditional 

    The googlePayResponse is used in the payment. This value should be URL encoded when it is entered into the secure hash generation process. 

    If the sent PaymentMethod parameter is 9 (Google Pay), this parameter is required

    • Field Type: Alphanumeric
    • Length: 64
    • Sample Data: -
    ItemID 
    optional     		The custom item ID for the merchant
    • Field Type: Alphanumeric
    • Length: 25
    • Sample Data: Item1
    BrowserLanguage 
    conditional

    An alphabetic value representing the browser language preference present in the http header

    It is required in case of channel is 0 and 1

    • Field Type: Alphanumeric 
    • Length: 99
    • Sample Data: en-US
    BrowserScreenHeight
    conditional

    Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.

    It is required in case of channel is 0 and 1

    • Field Type: Numeric
    • Length: 6
    • Sample Data: 768
    BrowserScreenWidth
    conditional

    Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.

    It is required in case of channel is 0 and 1

    • Field Type: Numeric
    • Length: 6
    • Sample Data: 1366
    BrowserScreenColorDepth
    conditional

    Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. The field values are: 

    • 1 -> 1 bit
    • 4 -> 4 bits 
    • 8 -> 8 bits 
    • 15 -> 15 bits 
    • 16 -> 16 bits 
    • 24 -> 24 bits 
    • 32 -> 32 bits 
    • 48 -> 48 bits
    It is required in case of channel is 0 and 1

    • Field Type: Numeric
    • Length: 2
    • Sample Data: 24
    BrowserTimeZone
    conditional

    Time difference between UTC time and the Cardholder browser local time, in minutes. The value is returned from the getTimezoneOffset() method.

    It is required in case of channel is 0 and 1

    • Field Type: Numeric
    • Length: 5
    • Sample Data: -120
    BrowserUserAgent
    conditional

    Exact content of the HTTP user-agent header.

    It is required in case of channel is 0 and 1

    • Field Type: Numeric
    • Length: 5
    • Sample Data: -120
    BrowserJavaScriptEnabled
    conditional

    Boolean that represents the ability of the cardholder browser to execute Java script.

    It is required in case of channel is 0 and 1

    • Field Type: Boolean
    • Length: -
    • Sample Data: true
    BrowserJavaEnabled
    conditional

    Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property

     It is required in case of channel is 0 and 1

    • Field Type: Boolean
    • Length: -
    • Sample Data: true
    BrowserAcceptHeader
    conditional

    Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser.

    It is required in case of channel is 0 and 1

    • Field Type: Alphanumeric
    • Length: -
    • Sample Data: */*
    ClientIPaddress
    conditional

    An alphanumeric value that represents the client’s public IP Address.

    It is required in case of channel is 0 and 1

    • Field Type: Alphanumeric
    • Length: 19
    • Sample Data: 79.183.118.666

    Response Parameters

    ParameterDescription

    Response.StatusCode  
    required

    An alphanumeric value that represents the response code that covers errors generated by the SmartRoute.  

    Check API Payment Response Codes Appendix for descriptive details about Response Codes

    • Field Type: Alphanumeric
    • Length: 5
    • Sample Data: 00000
    Response.StatusDescription  
    required

    An alphanumeric value that represents a message describing the response status received from SmartRoute. This parameter is filled only after a complete execution process using the language specified in the request.

    • Field Type: Alphanumeric
    • Length: 100
    • Sample Data: Transaction was processed successfully.
    Response.MerchantID 
    required

    An alphanumeric value that represents the unique ID of the merchant at SmartRoute. The SmartRoute operation team provides this value upon merchant enrollment.

    • Field Type: Alphanumeric 
    • Length: 40
    • Sample Data: MID0001
    Response.MessageID
    required

    An alphanumeric value that represents the action for defined unique number: 27 for Get card 3ds version

    • Field Type: Alphanumeric 
    • Length: 2
    • Sample Data: 27
    Response.ThreeDSVersion
    required    		An alphanumeric value that represents the 3DS Version, the available values are:
    • NONE
    • 3DS1
    • 2.1.0
    • 2.2.0
    • 2.3.0
    • Field Type: Alphanumeric
    • Length: 8
    • Sample Data: 2.1.0
    AuthenticationToken
    required     		AuthenticationToken Value send in response Header

    • Field Type: Alphanumeric
    • Length: 255
    • Sample Data: 27
    Response.MethodDataURL
    conditional

    ACS URL that should be used to POST MethodData. The value is URLEncoded

    It is required in case of channel is 0 and 1

    • Field Type: Alphanumeric 
    • Length: -
    • Sample Data: http://someacs/ 
    Response.MethodPostData
    conditional

    Method Data they should be posted to MethodDataURL. The value is URLEncoded

    It is required in case of channel is 0 and 1

    • Field Type: Alphanumeric
    • Length: -
    • Sample Data: -
    Response.RedirectHtml 
    conditional

    This parameter contains a complete HTML document that must be rendered by the merchant’s browser.
    It is used to automatically initiate the 3DS Method process by posting the required Method Data to the MethodDataURL via a hidden iframe. This allows the Access Control Server (ACS) to collect browser and device information needed for risk assessment.

    The returned HTML must be rendered exactly as received, without any modification.

    This parameter is returned only when 3DS Method execution is required.

    The merchant should inject this HTML into the page (for example, inside a container <div>).

    The merchant must wait for the 3DS Method execution to complete (using a timeout or browser messaging mechanism) before proceeding with the Authenticate Payer step.

    It is required in case of channel is 0 and 1

    • Field Type: Alphanumeric
    • Length: -
    • Sample Data: -



    What's Next