Implementation Guidelines

Last updated 10 months ago

Implementation Guidelines

Before you begin

Before you begin, you will need to have the following settings which will be provided to you by PayShield during the onboarding process:

txshield_3ds_url
txshield_3ds_sid
txshield_3ds_rcode

There are 7 steps to complete the 3DS SDK integration, the majority of which require updates to your current payment page/checkout page only.

If your authorisation (payment) processing is done through a provider other than TxShield, you are only required to complete steps 1-5.

1. Add the 3DS SDK

Add the 3DS Javascript Library to 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 (Provided by PayShield 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

Add the data-threeds attribute to all elements in the form that contain information relevant to 3DS authentication. 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.

'pan', 'month' and 'year' elements are mandatory.

<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. Initialise the 3DS SDK

Initialise/instantiate the 3DS SDK. This should be done on page load, as there are several network calls that are performed. If done on page load, these network calls can run in the background while the customer is completing the payment form.

let my3ds2 = new ThreeDS2('{formId}',
    '{txshield_3ds_sid}',
    '{amounttotal}',
    '{hash}',
    '{txshield_3ds_url}',
    '{merchantreference}',
    '{global window scope}',
    '{options}'
)

formid: The id attribute of your tag on your checkout page. This form should be your billing form that contains the data-threeds attributes detailed later. e.g. if the formid is 'billing-form' the form must have an id tag.
txshield_3ds_sid: Provided 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: The TxShield server url that you are integrating into. This will be provided to you at the 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 of 20 characters. If the length is over 20 characters, the reference will be automatically trimmed.
global window scope: The scope for the window in which the billing form is in. For most integrations, it will simply be this.

let options = {
    showChallenge: true,
    showChallengePopup: true,
    rebilling: true,
    rebillingData: {
        rebillingExpiry: "20231231",
        rebillingFrequency : 28
    }
}

4. Call the do3D() method

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

You should call the do3D() method after doing your initial data validation (making sure all fields are filled and are 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 is 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.

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

5. Handle 3DS result

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

If you are doing your payment processing through TxShield, there is nothing further for you to do with this data, other than to decide if you want to continue based on the transStatus.

If your payment processing is done through 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 contain up to two new input fields - threeDSecure and addinfo. If payment processing is through TxShield, these fields must exist and must be included in the final form submission. Do not remove them.

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

7. Submit for payment processing

Now that you have formatted the data for your payment provider, you can submit the payment for processing.

PreviousOverview Next3DS SDK Options

Last updated 10 months ago

Before you begin

Before you begin, you will need to have the following settings which will be provided to you by PayShield during the onboarding process:

txshield_3ds_url
txshield_3ds_sid
txshield_3ds_rcode

There are 7 steps to complete the 3DS SDK integration, the majority of which require updates to your current payment page/checkout page only.

If your authorisation (payment) processing is done through a provider other than TxShield, you are only required to complete steps 1-5.

1. Add the 3DS SDK

Add the 3DS Javascript Library to 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 (Provided by PayShield 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

'pan', 'month' and 'year' elements are mandatory.

<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. Initialise the 3DS SDK

let my3ds2 = new ThreeDS2('{formId}',
    '{txshield_3ds_sid}',
    '{amounttotal}',
    '{hash}',
    '{txshield_3ds_url}',
    '{merchantreference}',
    '{global window scope}',
    '{options}'
)

formid: The id attribute of your tag on your checkout page. This form should be your billing form that contains the data-threeds attributes detailed later. e.g. if the formid is 'billing-form' the form must have an id tag.
txshield_3ds_sid: Provided 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: The TxShield server url that you are integrating into. This will be provided to you at the 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 of 20 characters. If the length is over 20 characters, the reference will be automatically trimmed.
global window scope: 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 section.

let options = {
    showChallenge: true,
    showChallengePopup: true,
    rebilling: true,
    rebillingData: {
        rebillingExpiry: "20231231",
        rebillingFrequency : 28
    }
}

4. Call the do3D() method

The callback function is discussed more in

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

5. Handle 3DS result

In , a callback function was provided to do3D(). When authentication is complete, the callback function is called.

Authentication is considered complete when the customer has ended their interaction with the 3DS servers. Refer to the section to learn more 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 through TxShield, there is nothing further for you to do with this data, other than to decide if you want to continue based on the transStatus.

If your payment processing is done through another provider, you can use this callback to format the data for your provider.

6. Added input fields

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

7. Submit for payment processing

Now that you have formatted the data for your payment provider, you can submit the payment for processing.