Use the Trustly Lightbox Javascript library to build bank authorization workflows in your Cordova apps. Integrate the Select Bank Widget or the Trustly Lightbox to retrieve bank authorization data that can be used with other Trustly APIs.

When your set up is complete, your Cordova app renders the Trustly Lightbox. When an OAuth bank is selected, the customer is directed to a secure in-app browser or their mobile banking app. After successfully signing in, the URL scheme redirects the customer to your app and the Lightbox workflow continues.

If you need help with your integration, contact your Trustly representative or send your request to [email protected].

Prerequisites

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

Install the Trustly Javascript in Your Cordova app

Open the Cordova index.html file and add the following script:

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

When you're testing in the Trustly Sandbox, change the root url tosandbox.trustly.one and make sure your Access ID is correct for the sandbox environment.

Open the Cordova config.xml file and confirm it contains the following entry:

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

This entry is required to render the Trustly Lightbox correctly.

OAuth Configuration

To support OAuth login flows on mobile apps, the Trustly Lightbox interacts with secure in-app browser components. In some cases, it interacts with the customer's mobile banking app directly.

Banks that use OAuth login pages often have strict security policies which prohibit access to their login urls from WebViews. Trustly client libraries include functionality that simplifies OAuth handling. For more information about using OAuth login authorization flows with the Trustly Lightbox, see the OAuth Guide.

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

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

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 with a Request Signature

To ensure communications between the Trustly Lightbox SDK and the Trustly API are secure, add a requestSignature authentication request to request the server access key before rendering the Select Bank Widget or Trustly Lightbox. Most of the information in the establishData property should be fetched or calculated dynamically. For example:

// 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',
};

For more information about generating a requestSignature, see Securing Requests.

OAuth Specific Parameters

For OAuth bank integrations, add the metadata property and the integrationContext and urlScheme fields to the establishData object. These changes alter Lightbox behavior and allow integration with the cordova-plugin-oauth component. For example:

// 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: Make sure you 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>

In your JavaScript file, pass the id of the window element into the trustlyOptions object. The trustlyOptions is referenced when the Trustly object is invoked. For example:


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