API Reference

3DS Integration

Integrate with TxShield for 3DS2 Authentication using our JavaScript based 3DS SDK. The following section and the 3DS DOM elements describe how to connect to the 3DS SDK and the options available.

We also have a demo payment page that shows how simple it is to integrate. Instructions for the demo payment page are in the 3DS Demo Payment Page section.

Implementation Guidelines

Before you begin

Before you begin implementation you will need to have the following settings. They will be issued by TxShield when you begin integration:

  • txshield_3ds_url
  • txshield_3ds_sid
  • txshield_3ds_rcode

There are 7 steps to complete the 3DS SDK integration. Only the first 5 are mandatory if you are doing your Authorization (payment) processing through a different provider.

Most steps should see you only having to update your current payment page / check out page:

  1. Add the 3DS SDK
  2. Add data-threeds attributes
  3. Initialize the 3DS SDK
  4. Call do3D()
  5. Handle authorisation result
  6. Check the added input fields. only if Authorization Processing with TxShield
  7. Submit the form for payment process. only if Authorization Processing with TxShield

1. Add the TxShield 3DS2 Javascript Library to the payment page.

Include the 3ds SDK into the payment page <script src="{txshield_3ds_url}/js/3d2integrator.v3.dist.js"></script> {txshield_3ds_url} is the TxShield server url that you are integrating with. This will be given to you at time of onboarding.

<html>
    <body>
        <div class="your-page-content">
        <form id="billing-form" action="" method="post">
        </form>
        </div> <!-- End of page -->
        <script src="{txshield_3ds_url}/js/3d2integrator.v3.dist.js"></script>
        <script>
            let options = {
                showChallenge: true,
                showChallengePopup: true
            }
            let threeD2 = new ThreeDS2( "<insert-form-id-here>", "<txshield_3ds_sid>", "<amounttotal>","<hash>","<txshield_3ds_url>","<merchantreference>","this", "<options>");
            document.getElementById('billing-form').addEventListener('submit', function (e) {
                threeD2.do3D(fnresponse);
            })
        </script>
    </body>
</html>

2. Add "data-threeds" attributes to form elements.

To the elements in the form that contain information relevant to 3DS Authentication, add the data-threeds attribute. The 3DS SDK will search for all elements marked with a data-threeds attribute. The value for the attribute tells the script what data this field contains. Example is below.

The pan, month and year elements are mandatory.

Add data-threeds Attributes to elements

<input name='creditCardNumber' id='creditCardNumber' data-threeds='pan'>
<input name='cardMonth' id='cardMonth' data-threeds='month'>
<input name='cardYear' id='cardYear' data-threeds='year'>

3. Initialize the ThreeDS2 object.

Intialize / Instantiate the 3DS SDK. This should be done on page load, as there are several network calls that are done. If this is done on page load, these network calls can be done in the background while the user is completing the payment form.

let my3ds2 = new ThreeDS2('{formId}',
    '{txshield_3ds_sid}',
    '{amounttotal}',
    '{hash}',
    '{txshield_3ds_url}',
    '{merchantreference}',
    '{global window scope}',
    '{options}'
)
  • formid: Is the id attribute of your tag in your checkout page. This form should be your billing form that contains the data-threeds attributes detailed later. e.g. for the formid is 'billing-form' The form must have an id tag.
  • txshield_3ds_sid: this will be given to you at time of onboarding.
  • amounttotal: total amount to charge the customer in decimals. e.g. 10.00 12.34
  • hash: md5 of txshield_3ds_sid, amount, rcode e.g. in php md5(txshield_3ds_sid.amount.rcode)
  • txshield_3ds_url: is the TxShield server url that you are integrating too. This will be given to you at time of onboarding.
  • merchantreference: merchants reference for this transaction. The reference here should be the same one for the payment transaction. for 3ds 1 this has a max length 20 characters. If the length is over 20 characters reference will be auotmatically trimmed.
  • global window scope: this is the scope, for the window in which the billing form is in. For most integrations it will simply be this.
  • options: options should be a JavaScript object that contains the different options available to configure the SDK. A full list of options is available in the 3DS Options section.
let options = {
    showChallenge: true,
    showChallengePopup: true,
    rebilling: true,
    rebillingData: {
        rebillingExpiry: "20231231",
        rebillingFrequency : 28
    }
}

4. Call the do3D() method.

When the user has finished entering their card details and all other data-threeds tagged fields with data, you should start the 3DS work flow by calling the do3D() method. This would commonly be done when the user has submitted the payment form.

We would recommend calling the do3D() method after doing your initial data validation (making sure that the fields are filled out, and in the correct format etc.) This should avoid extra 3ds transactions and costs by sending empty fields.

The do3d() function accepts one parameter, a callback function. The callback function gets called when the authentication has been completed. There is one parameter sent to the callback function, it is a JavaScript object containing the result of the authentication.

The callback function is discussed more in step 5.

my3ds2.do3D(function (data)) {
    //my callback
});

5. Handle 3DS Result

In step 4, a callback function was provided to do3D(). When Authentication is completed, the callback function will be called.

Authentication is considered complete when the user has ended their interaction with the 3DS servers. Refer to the 3DS Response section to learn more details about the returned response and what it means.

Once the callback has been called, you can now submit your payment form for payment processing.

If you are doing your payment processing with us, you do not have to do anything else with this data, other than decide if you want to continue based on the transStatus.

If you are doing your payment processing with another provider, you can use this callback to format the data for your provider.

6. Added Input Fields

If the above steps are done correctly, the Form will have up to two new input fields created, threeDSecure and addinfo. If payment processing with us, these fields must exist, and must be included in the final form submission. Do not remove them.

Extra fields added to the form

If you aren't doing your processing with TxShield, 

<input class="threeDSecure" type="hidden" name="threeDSecure" value="">
<input class="addinfo" type="hidden" name="addinfo" value="" data-threeds="id">

7. Submit for payment

Now that you have formatted the data for your payment provider, whether through TxShield or another provider, you can now submit the payment for processing.