Trustly Widget

The Trustly Widget is the optimal method to present Trustly as a payment option to your customers. Simple, reliable, and secure, the Trustly Widget can be placed in your cashier alongside any other payment methods you offer.

The Trustly Widget allows your cashier to display the returning customer’s last-used account, enabling a quicker, simpler payment process.

When the merchant obtains the accountId via the Trustly Widget, the user is still able to switch accounts if the returned account has issues, such as insufficient funds, closure, etc. This enables both fast and regular payment options.

Getting started

The Trustly Widget is initialised and rendered using JavaScript. Below are code examples that can be used to achieve the desired rendering result.

Step 1. Add the DOM

Add the Trustly Widget container on the target page where you find it the most suitable.

<div id="trustly-widget"></div>
<!-- NOTE! Do not change the ID -->

🚧
The ID of the container should not be changed.

Step 2. Add Trustly Widget script

Add the Trustly Widget script in the head of your cashier page with defer attribute set. This ensures the script executes only after the page is parsed. Note that if you want to support older browsers you may need to use a different version.

Script	Source URL
Standard widget	https://checkout.trustly.com/widget/v1/script
Polyfilled widget	https://checkout.trustly.com/widget/v1/script-polyfilled

<html>
  <head>
      <script defer src="https://checkout.trustly.com/widget/v1/script"></script>
  </head>
  <body>
    <!-- Your checkout page -->
    <div id="trustly-widget"></div>
    <!-- Rest of your checkout page -->
  </body>
</html>

Initialisation

When the required HTML and scripts are set, the widget needs to be initialised to render it.

Step 1. Init

The script exposes an object containing a method to initialise the widget. This method should be called with the following parameters:

TrustlyWidget.init(EndUserID, Username, initCallback, Attributes);

Initiation arguments

Param	Description	Type	Required	Example
EndUserID	The EndUserID of the customer used in the Deposit API call.	string	Yes	“123123”
Username	The Username used with the Trustly API.	string	Yes	“merchant_username”
initCallback	Function to be called after initialisation. The 1st function parameter should be reserved for the data object provided in the callback.	function	Yes	function initCallback(data) { / Your code that results into initiating a Trustly order with or without the received data / }
Attributes	Optional configuration. See more details below.	object	No	{ Locale: “sv_SE” }

Callback data properties

Property	Type	Description	Example
AccountID	string	Account ID to be sent with the Trustly API call attributes	"9988776655"

Attributes properties

Property	Type	Description	Example
Locale	string	Language for the widget. Specified with ISO 639-1 locale and ISO 3166-1 alpha-2 country code.	"sv_SE"

Step 2. React on init status (optional)

The init() returns a promise which, when completed, returns one of two status codes:

FirstTimeUser
RecurringUser (returning Trustly user)

Best practice

The best way to use these status codes is to determine whether the customer is a returning Trustly user or not. If they are a returning user, move the Trustly Widget to the top of the cashier to streamline the payment process.

<div id="trustly-widget"></div>
<script>
  const EndUserID = "123123";
  const Username = "merchant_username";

  const initCallback = (data) => {
    	// Initiate Trustly Checkout order with provided callback data.
  }
  
  const Attributes = { 
    Locale: "sv_SE"
  };

  const initTrustlyWidget = async () => {
      try {
          const { status } = await TrustlyWidget.init(EndUserID, Username, initCallback, Attributes);
          /*
           Status values:
             - FirstTimeUser
             - RecurringUser
          */
      } catch (e) {
        // Handle error
      }
	}

  initTrustlyWidget();
</script>

Step 3. Initialise Trustly Checkout order

The provided callback being executed means that the Trustly Checkout order (i.e. Deposit call) can be created. If there was data provided in the callback, that should be added to the attributes of the Trustly Deposit API call.

// Your Trustly API order parameters
...
"Data": {
 ...
   "Attributes": {
      ...
        "EndUserID" : "12345",
        "Firstname" : "Steve",
        "Lastname" : "Smith",
        "Amount" : "10",
        "Currency" : "EUR",
        "Country" : "SE",
        "AccountID:" [received accountId from the widget]
    }
...