Trustly UI is a web-based module that enables users to securely create a bank authorization. Users must successfully authorize transactions through Trustly UI before data or payments APIs are utilized.

Trustly UI is is available for integration as a JavaScript library as well as native mobile SDKs for iOS and Android. Additionally, it can easily be integrated into mobile apps with frameworks such as React Native and Cordova as well as mobile webview.

Quickly get started with mobile development for:

• iOS
• Android
• React Native
• Cordova

JavaScript Library

Getting started with a web integration is as easy as including the Trustly JavaScript library on each page of your site. It must always be loaded directly from trustly.one, rather than downloaded, bundled or hosted from a custom domain.

<script src="https://trustly.one/start/scripts/trustly.js?accessId={YOUR_ACCESS_ID}"></script>

Make sure to replace YOUR_ACCESS_ID with the Access ID provided by Trustly and adjust the subdomain to include sandbox if you are using the sandbox environment.

The JavaScript library is used to either render the Select Bank Widget which then launches the Trustly Lightbox, or to launch the Trustly Lightbox directly.

Trustly Lightbox Implementation Options

Trustly UI offers two types of user experiences that can be configured to fit your application. The primary method is to render the Select Bank Widget which allows users to quickly search for and select a bank to begin the authorization process. The second method is to launch the Lightbox after a user taps a button.

In addition to determining if the Select Bank Widget or opening the Trustly Lightbox directly is the best option for you, Trustly has a number of Branding Requirements to consider. If you have any questions or specific requirements, work with your Trustly team or email [email protected].

Select Bank Widget

The Select Bank Widget represents an optional bank-selection shortcut. It is shown in-line on your page and highlights the most popular banks while adding the capability to quickly search for a bank not expressly represented. Selecting one of the buttons on the Select Bank Widget opens the Lightbox, where the user can authorize their account for use.

The Select Bank Widget can be launched by calling the selectBankWidget function of the Lightbox SDK. When you use the Select Bank Widget, the options parameter must contain a widgetContainerId where the ID of the html element to contain the widget is provided as the value. For example:

let TrustlyOptions = {
  hideCloseButton: true,
  dragAndDrop: true,
  widgetContainerId: "trustly-widget-id" //Page element container for the widget
};

Trustly.selectBankWidget(establishData, TrustlyOptions);

Launch Trustly Lightbox with a Button

When the Trustly Lightbox is launched by a user tapping a button, the Trustly Lightbox opens over the existing page and presents a longer, scrollable and searchable list of banks.

The Lightbox can be launched by calling the establish function of the Lightbox SDK and can be configured via the options parameter. For example:

Trustly.establish(establishData, options);

Establish Data

Displaying the Select Bank Widget or launching the Lightbox directly requires various pieces of data passed into the data argument. The data required may vary for the type of transactions your app supports, however the following properties are always required:

• accessId - string value associated with your API keys (provided by Trustly during onboarding)
• merchantId - string value associated with your API keys (provided by Trustly during onboarding)
• paymentType - string The payment transaction category your app requires. See Payment Types.
• returnUrl - Redirect URL to be called when a user successfully creates a bank authorization.
• cancelUrl - Redirect URL to be called when a user cancels from the Lightbox or the bank authorization is otherwise unsuccessful.

Example establish data object:

{
  "merchantId": "YOUR_MERCHANT_ID",
  "accessId":"YOUR_ACCESS_ID",
  "requestSignature": {requestSignature},
  "merchantReference": {unique_merchant_payment_identifier},
  "description": "any additional user-friendly descriptive information for the payment",
  "paymentType": "Deferred",
  "currency": "USD",
  "amount": "0.00",
  "customer": {
    "name": "Joe User",
    "email": "[email protected]",
    "address": {
      "address1": "2000 Broadway St",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063",
      "country": "US"
    }
  },
  returnUrl: "https://yourapp.com/path/return",
  cancelUrl: "https://yourapp.com/path/cancel"
}

Configuration Options

Both the Select Bank Widget and Lightbox can be configured by passing various properties into the options parameter.

Example Configuration Options

let TrustlyOptions = {
  hideCloseButton: true,
  dragAndDrop: true,
  widgetContainerId: "widget-id" //Page element container for the widget
};

You can specify the following Trustly Configuration Options in your request: