# 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\_mid
* 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.
1. [Add the 3DS SDK](#1.-add-the-3ds-sdk)
2. [Add data-threeds attributes](#2.-add-data-threeds-attributes-to-form-elements.)
3. [Initialise the 3DS SDK](#3.-initialise-the-3ds-sdk)
4. [Call the do3D() method](#4.-call-the-do3d-method.)
5. [Handle 3DS result](#5.-handle-3ds-result)
6. [Check the added input fields](#6.-added-input-fields)
7. [Submit for payment processing](#7.-submit-for-payment)
{% hint style="info" %}
*If your authorisation (payment) processing is done through a provider other than TxShield, you are only required to complete steps 1-5.*
{% endhint %}
### 1. Add the 3DS SDK
Add the 3DS Javascript Library to the payment page ``
*{txshield\_3ds\_url}* is the TxShield server URL that you are integrating with (Provided by PayShield at time of onboarding).
```
```
### 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.
{% hint style="warning" %}
'pan', 'month' and 'year' elements are mandatory.
{% endhint %}
```
```
### 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_mid}',
'{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\_mid**: 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\_mid, amount, rcode e.g. in php **md5(txshield\_3ds\_mid.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 [3DS SDK Options](/3dsecure2+/3ds-sdk-options.md) section.
```
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.
The callback function is discussed more in [step 5.](#5.-handle-3ds-result)
```
my3ds2.do3D(function (data)) {
//my callback
});
```
### 5. Handle 3DS result
In [step 4](#4.-call-the-do3d-method.), 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 [3DS Response](/3dsecure2+/3ds-response.md) 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
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.**
```
```
### 7. Submit for payment processing
Now that you have formatted the data for your payment provider, you can submit the payment for processing.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payshield.ai/3dsecure2+/implementation-guidelines.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.