1. Home
  2. Docs
  3. Integrating with i=Change
  4. Custom implementation
  5. JS Integration Library

JS Integration Library

Overview

This document provides brands/developers to integrate with i=Change platform using the JavaScript library provided. The library simplifies the process of collecting and transmitting data to i=Change platform.

Basic Authentication Library

Initialization

To start with, initialize the necessary configurations to be able connect to the platform. Such configs will be given to you by i=Change team.

ParametersDescription
siteIdId of the brand
sitePasswordKey of the brand
var config =  {
    siteId:'<siteId>',
    sitePassword:'<sitePassword>'
};
IEqualChangeLibrary.init(config);

Event Listener

The library provides a method to trigger / call the iEqualChange platform.

ParametersDescription
productionSrcProduction url for integration
testingSrcStaging / testing url for integration
var IEqualChangeLibrary = (function (){
var siteId;
var sitePassword;
var productionSrc='https://share.iequalchange.com/static/js/js_donate';
var testingSrc='https://staging.share.iequalchange.com/static/js/js_donate';
    function init(config){
        siteId = config.siteId;
        sitePassword = config.sitePassword;
    }
    function sendDonation(orderData, isTesting){
        var {
            orderId = '',
            firstName = '',
            lastName = '',
            email = '',
            postcode = '',
            state = '',
            country = '',
            totalAmount = ''
        } = orderData;
        var src = isTesting ? testingSrc : productionSrc;
        var iecScript = document.createElement('script');
        iecScript.setAttribute('data-iec-orderid', orderId);
        iecScript.setAttribute('data-iec-first-name', firstName);
        iecScript.setAttribute('data-iec-surname', lastName);
        iecScript.setAttribute('data-iec-customer-email', email);
        iecScript.setAttribute('data-iec-postcode', postcode);
        iecScript.setAttribute('data-iec-state', state);
        iecScript.setAttribute('data-iec-country', country);
        iecScript.setAttribute('data-site-id', siteId);
        iecScript.setAttribute('data-iec-site-password', sitePassword);
        iecScript.setAttribute('data-iec-total-amount', totalAmount);
        iecScript.setAttribute('src', src);
        document.head.appendChild(iecScript);
    }
    return {
        init:init,
        sendDonation:sendDonation
    };
})();

Parameters

These parameters are to be passed to i=Change platform and be able to have to do a successful donation.

ParametersDescription
orderId  Unique order id of the customer (required)
firstNameThe customer’s first name
lastNameThe customer’s last name
emailThe customer’s email address (required)
postcodeThe customer’s postal / zip code
stateThe customer’s state/ province
countryThe customer’s country
totalAmountServe as the total amount of the item purchase before shipping and tax.
This value is used to calculate % of cart donation values. Set to 0 if not needed.
var orderData = {
    orderId : '<orderId>',   
    firstName : '<firstName>',
    lastName : '<lastName>',
    email : '<email>',
    postcode : '<postcode>',
    state : '<state>',
    country : '<country>',
    totalAmount '<totalAmount>': 
};
IEqualChangeLibrary.sendDonation(orderData,true);

Encrypting the payload

When sending data to the i=Change System the JSON package is encrypted using a symmetric encryption algorithm. The reason for the encryption is to ensure only legitimate transactions are sent to the i=Change system, and to prevent Cross-site request forgery (CSRF) attacks.

In order to encrypt the JSON package the Site Key for the client site is required. This same Site Key will be used by the i=Change System to decrypt the JSON package. If an invalid Site Key is used during encryption the i=Change System will reject the request.

The process for encrypting the JSON package so that it is compatible with the i=Change System is explained below:

  1. Create the Binary Site Key:
    a. Calculate the Site Key Binary Hash by taking the MD5 hash of the Site Key as bytes (not as a HEX string)
    b. The Binary Site Key is then the first 8 bytes of the Site Key Binary Hash
  2. Calculate the Binary Payload by encrypting the JSON package using the TripleDES algorithm and ECB cipher mode

Convert the Binary Payload into a BASE64 string suitable for embedding in a HTML document, referred to as the Payload. The data is encrypted using the SecureTransport.php class and it’s ‘encrypt’ function.

Sending the payload

To complete this section will require three variables that are provided outside the scope of the document. These will be referenced in the code examples below.

  1. <Site url>
  2. <Site ID>
  3. <Site key>

Once the Payload has been constructed with all the collected transaction information it can be sent to the i=Change System. To trigger the i=Change System popup window a small amount of HTML code needs to be inserted into the final page of the booking process. This code should be inserted on the Thankyou page that is returned after a successful payment transaction has completed:

<script src=”<Site url>/static/js/load”
data-iec-location= ”<Site url>”
data-site-id=”<Site ID>”
data-payload=”<Encrypted Data>”>
</script>
<script>
iec(<Site url>,
“<Site ID>”,
“<Encrypted Data>”
</script>

Example code with replaced variables

This code shows how the replaced code should appear with replaced variables. The following is an example and should not be used in any testing and provided as guidance only.

<script src=” https://thiswebsite.com/connect/static/js/load”
data-iec-location= ” https://thiswebsite.com/connect/”
data-site-id=”xd7”
data-payload=”<Encrypted Data>”>
</script>
<script>
iec(https://thiswebsite.com/connect/”,
“<xd7”,
“<Encrypted Data>”
</script>

In the code above refers to the numeric site/client ID in the i=Change System database enclosed in double quotes (“), and is the BASE64 encoded Payload also enclosed in quotes (“).

Sample Code

Full sample Javascript code below.

<script>
    var IEqualChangeLibrary = (function (){
        var siteId;
        var sitePassword;
        var productionSrc = 'https://share.iequalchange.com/static/js/js_donate';
        var testingSrc = 'https://staging.share.iequalchange.com/static/js/js_donate';
        function init(config){
            siteId = config.siteId;
            sitePassword = config.sitePassword;
        }
        function sendDonation(orderData, isTesting){
            var {
                orderId = '',
                firstName = '',
                lastName = '',
                email = '',
                postcode = '',
                state = '',
                country = '',
                totalAmount = ''
            } = orderData;
            var src = isTesting ? testingSrc : productionSrc;
            var iecScript = document.createElement('script');
            iecScript.setAttribute('data-iec-orderid', orderId);
            iecScript.setAttribute('data-iec-first-name', firstName);
            iecScript.setAttribute('data-iec-surname', lastName);
            iecScript.setAttribute('data-iec-customer-email', email);
            iecScript.setAttribute('data-iec-postcode', postcode);
            iecScript.setAttribute('data-iec-state', state);
            iecScript.setAttribute('data-iec-country', country);
            iecScript.setAttribute('data-site-id', siteId);
            iecScript.setAttribute('data-iec-site-password', sitePassword);
            iecScript.setAttribute('data-iec-total-amount', totalAmount);
            iecScript.setAttribute('src', src);
            document.head.appendChild(iecScript);
        }
        return {
            init:init,
            sendDonation:sendDonation
        };
    })();
    var config =  {
        siteId:'999',
        sitePassword:'c7bdad8a-af06-43fa-b674-69beaccaf7d5'
    };
    IEqualChangeLibrary.init(config);
    var orderData = {
        orderId : '12314111',
        firstName : 'Legend',
        lastName : 'Cross',
        email : 'legend.cross@email.com',
        postcode : '4216',
        state : 'VIC',
        country : 'Australia',
        totalAmount : 2
    };
    IEqualChangeLibrary.sendDonation(orderData,true);
</script>

Additional Notes

  1. The Javascript code was an example on how to integrate with iEqualChange library and it can be revised according to the brand needs.
  2. Code should be placed in web root folder to track origin to match the domain is using the script that we have whitelisted.
  3. Total amount can be set to 0 if not using % donations, but we recommend including where available. Fixed donation is to be set at the Admin Portal of iEqualChange application.
  4. Parameters can be set in html textboxes to passed through iEqualChange library.
  5. Parameters especially the siteId & sitePassword values should not be visible to anyone and/or browser consoles. Store it to a file, AJAX call or a POST value to be sent to this library
var orderData = {
        orderId : Math.floor(Math.random() * 100000).toString(),
       
firstName : document.getElementById(“textFirstName”).value,
        lastName : document.getElementById(“textLastName”).value,
        email : document.getElementById(“textEmail”).value,
        postcode : document.getElementById(“textPostCode”).value,
        state : document.getElementById(“textState”).value,
        country : document.getElementById(“textCountry”).value,
        totalAmount : document.getElementById(“textTotalAmount”).value,
    };

Revision History

VersionDateAuthor(s)Revision Notes
1.2May 17, 2024Edmar B. CruzRevised previous document format Revised code structure Total amount parameter Notes

How can we help?