Summary

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 fully responsive and 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.

Lightbox Overview

User Flow

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 secondary method is to launch the Lightbox directly from 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, please 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. Note that when using 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:

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

Trustly.selectBankWidget(establishData, TrustlyOptions);

Directly Launch the Lightbox

Alternatively, you can launch the Trustly Lightbox directly from a button. In this case, the Lightbox opens over your 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.

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.

📘

Mobile SDK Redirects

When using the Lightbox SDK for iOS or Android the returnUrl and cancelUrl properties are not required. Instead, the SDKs provide onReturn and onCancel callback functions that can be utilized to handle the Lightbox responses.

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: