The Trustly Lightbox Javascript library allows you to quickly build a bank authorization workflow in your Cordova app. Integrating the Select Bank Widget and/or the Trustly Lightbox provides a powerful user experience that results in bank authorization data which can be used with other Trustly APIs.

OAuth Background

Banks that use OAuth login pages often have strict security policies which prohibit user access to their login urls from inside Webviews. Trustly has added functionality to our client libraries in order to make OAuth handling simpler, this guide includes the steps required to properly handle OAuth flows via secure in-app browser components.

For more information visit the OAuth Guide

Setup

Requirements

• iOS (cordova-ios >= 6.1.0)
• Android (cordova-android >= 9.0.0)
• A configured Deep Link (e.g. URL Scheme) for your app

Installation

1. Since Cordova uses plain HTML and Javascript, installing the Trustly Javascript in your Cordova app is as easy as adding the following script to your index.html page.

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

If testing in the Trustly Sandbox environment, remember to adjust the root url to sandbox.trustly.oneand check to make sure your Access ID is correct for that environment.

1. If not already configured, check that your config.xml file allows navigation. This is required for the Trustly Lightbox to render correctly:

<widget>
    ...
    <allow-navigation href="*" />
</widget>

OAuth Configuration

In order to support OAuth login flows on mobile apps, the Trustly Lightbox interacts with secure in-app browser components and in some cases it hands off to the user's mobile banking app directly. These steps are required for a successfuly Trustly integration.

1. Configure a urlScheme within your app. This should be configured by default as the widget id in your config.xml file.

<widget id="yourapp" version="1.0.0">

1. To integrate secure in-app browser functionality in iOS and Android add Trustly’s fork of the cordova-plugin-oauth and reference your app’s URL_SCHEME using the variable shown below:

cordova plugin add https://github.com/TrustlyInc/cordova-plugin-oauth --variable URL_SCHEME=yourapp

Define Establish Data

As the Trustly Lightbox SDK runs on the client, requests between it and the Trustly API must be secured. Calculate a requestSignature using your Access Key from your server and fetch it from your Android app prior to rendering the Select Bank Widget or Trustly Lightbox.

See Securing Requests for more details on generating a requestSignature.

In addition to the requestSignature much of the other information in the establishData properties should be fetched or calculated dynamically. For simplicity in this example it is primarily hardcoded into the view:

// index.js

const establishData = {
    accessId: "YOUR_ACCESS_ID",
		merchantId: "YOUR_MERCHANT_ID",
    // requestSignature: REQUEST_SIGNATURE, <-- this is required in production
    description: 'your transaction description',
    merchantReference: 'ABCDREF',
    paymentType: 'Retrieval',
};

OAuth Specific Parameters

To complete the requirements for OAuth bank integrations, two additional fields must be added to a metadata property on the establishData object. These elements will configure the Lightbox element to alter its behavior when an OAuth bank is selected and integrate behind the scenes with the cordova-plugin-oauth component that was added earlier.

// index.js

const establishData = {
    accessId: "YOUR_ACCESS_ID",
		merchantId: "YOUR_MERCHANT_ID",
    // requestSignature: REQUEST_SIGNATURE, <-- this is required in production
    description: 'your transaction description',
    merchantReference: 'ABCDREF',
    paymentType: 'Retrieval',
		metadata: {
			integrationContext: "InAppBrowser",
			urlScheme: "YOUR_APP_URL_SCHEME://oauth_callback"
};

Note: it is important to add the oauth_callback path to your app’s URL scheme.

Display the Select Bank Widget

Define an HTML component to anchor the Select Bank Widget and then render it by calling the selectBankWidget function from the Trustly object attached to the window element. For example:

<!DOCTYPE html>
<html>
    <head>
				...
        <script src="cordova.js"></script>
        <script src="https://trustly.one/start/scripts/trustly.js?accessId={YOUR_ACCESS_ID}"></script>
	      <script src="js/index.js"></script>  
    </head>
    <body>
        <div class="app">
            <h1>Checkout with Trustly</h1>
            <div id='trustlyWidget'></div>
        </div>
    </body>
</html>

Then from your Javascript file, pass the id of the element referenced above into the trustlyOptions object which is then referenced when the Trustly object is invoked.

const establishData = {
    accessId: "YOUR_ACCESS_ID",
		merchantId: "YOUR_MERCHANT_ID",
    // requestSignature: REQUEST_SIGNATURE, <-- this is required in production
    description: 'your transaction description',
    merchantReference: 'ABCDREF',
    paymentType: 'Retrieval', // or the applicable paymentType
};

const trustlyOptions = {
    closeButton: true,
    dragAndDrop: false,
    widgetContainerId: "trustlyWidget"
};

function onDeviceReady() {
		...
		// render the Select Bank Widget
    window.Trustly.selectBankWidget(establishData, trustlyOptions)
}

Summary

With these elements in place, your Cordova app will seamlessly render the Trustly Lightbox and when an OAuth bank is selected, the user will be directed to a secure in-app browser or in some cases directly to their mobile banking app. Upon successful login, they will be redirected to your app via the URL scheme and the Lightbox user flow will proceed.

If you have any questions or need support in your integration, reach out to [email protected]