Contents x
    3D-Secure Implementation
    • 28 Aug 2023
    • 5 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Contents

    3D-Secure Implementation

    • Updated on 28 Aug 2023
    • 5 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Article summary

    Overview

    3-D Secure™ is a security protocol used to authenticate users. This provides an extra layer of protection for payments and card-not-present transactions. It was designed to allow a cardholder to do the authentication in order to prevent payment fraud, stymie unauthorized transactions, and reduce chargebacks.


    Implementation

    This section guides the merchants who are using API Payment or API PreAuth on how to deal with 3D-Secure implementation. This implementation will cover both versions of 3DS (1.x and 2.x).

    For merchants who are using this type of integration, they are responsible to capture the card details and send the request to SmartRoute via API Payment or API PreAuth, etc. 

    In case there is a need for authentication, SmartRoute will respond back indicating that the authentication is required along with some specific parameters. Once the authentication is done from the merchant side, the merchant shall send an API Approve request to SmartRoute along with authentication result that came out from the authentication process. 

    The above can be described in the below steps to make it simplified for merchants:

    Step 1

    Merchants are requested to use ThreeDSMethodRequestor API prior to submitting the request to SmartRoute. This API will help in collecting user's browser information required for authentication. Follow below points to achieve step 1.

    1. Include threeds.js file.
    2. Once the HTML page finished the loading (the document is ready), merchant shall configure ThreeDSMethodRequestor by calling static method configure(MethodDataURL, MerchantID, TransactionID, ItemID,MessageID, ExtraDetails, AutomaticGetMethodData,ShowLoader, FailureCallback).
    3. Make sure to set ‘ExtraDetails’ according to the specifications in the below table.
    ParameterDescription
    MethodDataURL
    required

    This value should be provided by the support team to the merchant upon enabling EMV 3DS. It represents the URL at SmartRoute side to submit the request to.

    • Field Type: Alphanumeric
    • Length: 1024
    • Sample Data: https://payone.io/SmartRoutePaymentWeb/GetMethodDataServlet
    MerchantID
    required

    Alphanumeric value represents 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 spaces.

    • Field Type: Alphanumeric
    • Length: 20
    • Sample Data: 1440954863817
    ItemID
    optional

    The custom item ID for the merchant. If this value is not present, then it can be an empty string or NULL.

    • Field Type: Alphanumeric
    • Length: 25
    • Sample Data: Item1
    MessageID
    required

    Represents the message id/transaction type that the merchant is going to perform.

    Possible Values:
     
    • 8 for API Payment.
    • 13 for API-PreAuth
    • Field Type: Numeric
    • Length: 2
    • Sample Data: 8

    ExtraDetails
    required

    A JSON object represents the following elements. This object will be used in automatic Get Method Data.

    Element NameDescriptionTypeInput
    formId
    required    		The name of the HTML formN/AN/A
    cardSource
    required     		It can be 'Card' or 'Token'N/AN/A
    card
    required
    		The card number entered by the userExact Field ID located in the HTML form for the field containing the card numberfieldId
    selectedPaymentMethod
    required
    		Represents the selected payment method. It should be always 1.1value
    cardExpiryMonth
    required
    		Represents Card Expiry MonthExact Field ID located in the HTML form for the field containing the month of card expiryfieldId
    cardExpiryYear
    required
    		Represents the Card Expiry YearExact Field ID located in the HTML form for the field containing the year of card expiryfieldId
    currency
    required
    		Represents the  currency of the transactionExact Field ID located in the HTML form for the field containing the currencyfieldId
    • Field Type: JSON
    • Length: N/A
    • Sample Data: 
    {  formId :"paymentForm",
     cardSource:"Card",
     card:{ input :"cardNumber",type:"fieldId"},
     selectedPaymentMethod:{ input : "1", type:"value"},
     cardExpiryMonth: { input :"expiryDatemm", type:"fieldId"},
     cardExpiryYear: { input :"expiryDateyy", type:"fieldId"},
     currency:{ input :"currencyCode",type:"fieldId"}
};

    AutomaticGetMethodData
    required

    Boolean value indicates if Get Method Data will be performed automatically or NOT.

    Possible Values:
     
    • True - Automatic is the only option is available for the time being
    • Field Type: Boolean
    • Length: N/A
    • Sample Data: True
    ShowLoader
    required

    Boolean value indicates if a loader will be displayed during the execution of Get Method Data or NOT.

     Possible values: 
    • True - Loader will be launched.
    • False - Loader will NOT be launched.
    • Field Type: Boolean
    • Length: N/A
    • Sample Data: True
    FailureCallback
    optional

    The JS function to be called after failed execution of Get Method Data. It can be NULL.

    • Field Type: JS Fucntion
    • Length: N/A
    • Sample Data: function sayHi() {alert(‘hi’);};


    <script src="https://smartroute.payone.io/script/threeds.js"></script> <script> function failureCallback(errorMessage) { alert(errorMessage); } window.addEventListener('load', function(e) { var methodDataServlet = 'https://smartroute.payone.io/SmartRoutePaymentWeb/GetMethodDataServlet'; var pun = 'testPUN123'; var itemId = null; var messageId = '8';//API Payment;because the middleware uses API Payment to integrate with smartoute var mid = 'testMerchant'; var paymentMethod = '1'; var extraDetails = { formId :'paymentForm', cardSource:'Card', card:{ input :'cardNumber',type:'fieldId'}, selectedPaymentMethod:{ input : paymentMethod, type:'value'}, cardExpiryMonth: { input :'expiryDatemm',type:'fieldId'}, cardExpiryYear: { input :'expiryDateyy',type:'fieldId'}, currency:{ input :'currencyCode',type:'fieldId'} }; ThreeDSMethodRequestor.configure(methodDataServlet, mid, pun, itemId, messageId, extraDetails, true, true, failureCallback); }); </script>


    Step 2

    When the customer wants to proceed with payment, merchant shall ask the customer to fill the card details to do the purchase. Once these details are captured, merchant has to send an API Payment or API PreAuth request to SmartRoute. If the authentication is required, then SmartRoute will respond back indicating that authentication must be done prior to conducting this payment transaction.

    Note: 
    Merchant must proceed with 3DS authentication when the “Response.StatusCode” provided back from SmartRoute in API Payment/API PreAuth was 20001.

    As part of API Payment and API PreAuth response, the following parameters are required to perform the authentication when it's required.

    • Response.PaReq represents Payment Authentication Request.
    • Response.AuthenticationURL represents the URL where the user will authnticates his payment.


    Step 3

    Merchant uses “Response.AuthenticationURL” to popup or redirect the user to the this URL (Response.AuthenticationURL), where the cardholder must authenticate his/her payment request. Also, “Response.PaReq”, which represents the Payment Authentication Request to be sent as a hidden field. 

    Simply, merchant can construct an HTML form as the below sample and take into consideration the following points:

    • The action of the HTML form should be Response.AuthenticationURL.
    • The HTTP method of the form should be POST.
    • Response.PaReq to be part of the form as hidden field.
    • TermURL represents the URL where the issuer will redirect back the customer once the authentication is performed.
    • MD represents a Payment Unique Number. This value will be echoed back within the redirection back from issuer side to merchant side.
    <html>
<body onload="document.form1.submit()">
<form name="AutoSubmitForm" action="<%= Response. AuthenticationURL %>" 
method="POST"> 
<input type="hidden" name="PaReq" value="<%=Response.PaReq%>"> 
<input type="hidden" name="TermUrl" value="<%= 
response.encodeUrl("https://merchant-return-URL")%>"> 
<input type="hidden" name="MD" value="echo"> 
</form>
</body>
</html>


    Step 4

    once the customer do the authentication at issuer side, issuer is responsible to redirect the customer back to the merchant side according to the provided TermURL value described in the previous step.

    The below sample shows how the submitted form from issuer to merchant will look like where:

    • merchant-return-URL  - represents the merchant URL where the issuer redirect back the customer. It's the TermURL        value provided tot he issuer when the merchant redirected the customer there.
    • PaRes  - represents Payment authentication response.
    • MD  - the echoed back value. It's the same value sent by the merchant when the customer redirected to the issuer.
    <HTML>
<BODY onload="document.form1.submit()">
<FORM NAME="postPAResToMPIForm" ACTION="https://merchant-return-URL" 
METHOD="post"> 
 <INPUT TYPE="hidden" NAME="PaRes" 
VALUE="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"> 
<INPUT TYPE="hidden" NAME="MD" VALUE="echo"> 
</BODY>
</HTML>


    Step 5

    At this point, we can say that authentication is done and the merchant shall submit a request to SmartRoute providing any authentication result and surely according to the specification of API Approve or any other subsequent message.

    What's Next