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 initialized and rendered using JavaScript. Below are code examples that can be used to achieve the desired rendering result.

Step 1. Add DOM

Add the Trustly Widget container on the target page where you find it the most suitable. Note that the ID of the container should not be changed.

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

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.

<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>

Initialization

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

Step 1. Init

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

TrustlyWidget.init(endUserID, username, merchantCallback, options);

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”

merchantCall back

Function to be called after initialization. The 1st function parameter should be reserved for the data object provided in the callback.

function

Yes

function widgetCallback(data) { // your code that results into
initiating a Trustly order with or without the received data
}

options

Optional configuration. See more details below.

object

No

{ locale: “sv_SE” }

merchantCallback data

Property

Type

Description

Example

accountId

string

Account ID to be sent with the Trustly API call attributes

"9988776655"

Options data

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. (Optional) React on init status

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.

<script>
const endUserID = "123123";
const username = "merchant_username";
const merchantCallback = function (data) { // Checkout initialization }; const options = { locale: "sv_SE" };
  try {
    await TrustlyWidget.init(endUserID, username, merchantCallback, options);
} catch (e) {
// Your code goes here
}
</script>

Step 3. Initialize 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]
} }
...