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.
The Trustly Widget is initialised and rendered using JavaScript. Below are code examples that can be used to achieve the desired rendering result.
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.
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>
When the required HTML and scripts are set, the widget needs to be initialised to render it.
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” |
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>
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]
}
...