Trustist Ecommerce JavaScript SDK

The Trustist Ecommerce JavaScript SDK provides an easy way to integrate the payment processing into your web application, whether it’s an e-commerce checkout or a charity donation page. The SDK handles user interactions and communicates with your server, which in turn interacts with the Trustist Ecommerce API securely.

SDK Integration #

To use the SDK, first, include the SDK script in your HTML file. Replace {{client_id}} with your actual client ID.

<script src="https://sdk-sandbox.trustistecommerce.com/js/sdk.js?client-id={{client_id}}" async></script>

 Using the SDK to create payments in a Web Application #

Here’s a generic example of how to use the Trustist Ecommerce SDK in your web application:

1. Create a <div> element in your HTML file where the payment button will be rendered:

<div id="trustistEcommerce"></div>

1. Add the following JavaScript code to your HTML file, adjusting the createPayment and paymentComplete functions to interact with your server:

<script>
    window.trustistReadyCallback = function () {
    trustist.ecommerce.Payment({
        createPayment: () => {
            // Call your local API to create a Trustist payment
            // Then use the response to return the payment URL to the SDK for use in the button
            return fetch("/api/payments", {
                method: "post",
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    orderId: "your_order_id",
                    returnUrl: "your_return_url"
                }),
            })
            .then((response) => response.json())
            .then((payment) => payment.payLink);
        },
        paymentComplete: (payment) => {
            // Called by the SDK on return from the Trustist payment process
            // Giving an opportunity to call the Trustist API via your local server
            // And using the response to decide on the next course of action
            // Check with the API directly to get a verified result
            return fetch("/api/payments/" + payment["tr-payment-id"], {
                method: "get",
            })
            .then((response) => response.json())
            .then((payment) => {
                if (payment.status === "COMPLETE") {
                    window.location.href = "ThankYou";
                } else {
                    // Handle unsuccessful payment
                }
            });
        }
    }).render("#trustistEcommerce"); // Render the created button into the nominated div
    };
</script>

In this example, replace your_order_id and your_return_url with your actual order ID and return URL values. The createPayment function should make a POST request to your server, which in turn communicates with the Trustist Ecommerce API to create a payment. The paymentComplete function is called when the user returns from the payment process, allowing you to verify the payment status with the Trustist Ecommerce API via your server.

With this setup, your server handles all the communication with the Trustist Ecommerce API securely, and your web application can update the user interface based on the payment status without exposing sensitive information.

Using the SDK to create standing orders in a Web Application #

Here’s a generic example of how to use the Trustist Ecommerce SDK in your web application:

• Create a <div> element in your HTML file where the payment button will be rendered:

<div id="trustistEcommerce"></div>

• Add the following JavaScript code to your HTML file, adjusting the createStandingOrder and paymentComplete functions to interact with your server:

<script>
    window.trustistReadyCallback = function () {
    trustist.ecommerce.Payment({
        createStandingOrder: () => {
            // Call your local API to create a Trustist payment
            // Then use the response to return the payment URL to the SDK for use in the button
            return fetch("/api/standingorders", {
                method: "post",
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    orderId: "your_order_id",
                    returnUrl: "your_return_url"
                }),
            })
            .then((response) => response.json())
            .then((payment) => payment.payLink);
        },
        paymentComplete: (payment) => {
            // Called by the SDK on return from the Trustist payment process
            // Giving an opportunity to call the Trustist API via your local server
            // And using the response to decide on the next course of action

            // Check with the API directly to get a verified result
            return fetch("/api/standingorders/" + payment["tr-payment-id"], {
                method: "get",
            })
            .then((response) => response.json())
            .then((payment) => {
                if (payment.status === "ACTIVE") {
                    window.location.href = "ThankYou";
                } else {
                    // Handle unsuccessful payment
                }
            });
        }
    }).render("#trustistEcommerce"); // Render the created button into the nominated div
    };
</script>

Like the process used to create a payment, the process to create a standing order involves passing your order ID into your API, where it contacts the TrustistEcommerce API directly to avoid anyone tampering with the request to create a standing order.  On the customer’s return from the Trustist payment screens the paymentComplete method will be called, which demonstrated by the code here calls back into your local API to get the result of the standing order, again without allowing request tampering between our servers.  The URL structure suggested in these snippets is not mandated and serves only as a demonstration.

Customising the appearance of the button #

This section explains how you can customize the appearance of the button created by the TrustistEcommerce JavaScript SDK. You can specify various properties such as button text, colors, and loading text through the render function parameters.

Basic Example #

To render a payment button, you need to call the render function of the trustist.ecommerce.Payment object. Similarly, to render a standing order button, you call the render function of the trustist.ecommerce.StandingOrder object.

Here is an example of how to use the script:

    <script>
        trustist.ecommerce.Payment({
            createPayment: async function() {
                // Your logic to create a payment
            }
        }).render({
            path: "#payment-button-container",
            buttonText: "Pay Now",
            buttonColour: "#28a745",
            textColour: "#ffffff",
            buttonHoverColour: "#218838",
            textHoverColour: "#ffffff",
            loadingText: "Processing..."
        });
    </script>

Customization Options #

The render function accepts an object with the following properties for customizing the button’s appearance:

1. path (String): The CSS selector for the element where the button will be rendered.
   • Example: "#payment-button-container"
2. buttonText (String): The text displayed on the button.
   • Example: "Pay Now"
3. buttonColour (String): The background color of the button in its default state.
   • Example: "#28a745" (green)
4. textColour (String): The text color of the button in its default state.
   • Example: "#ffffff" (white)
5. buttonHoverColour (String): The background color of the button when hovered.
   • Example: "#218838" (darker green)
6. textHoverColour (String): The text color of the button when hovered.
   • Example: "#ffffff" (white)
7. loadingText (String): The text displayed on the button when it is in a loading state after being clicked.
   • Example: "Processing..."