The Trustly Lightbox SDK for iOS allows you to quickly build a bank authorization workflow in your iOS 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.

💻
Example App
Prefer running an example project? Checkout our Swift iOS Example App on Github.

Set Up

Requirements

iOS 12 or above
Xcode 14 or above

Installation

📘
Legacy Versions
v4 SDKs deprecate v3 references.
v3 SDKs deprecated PayWithMyBank references. If your app previously used version 2, update these references to Trustly when upgrading to a v3 SDK.

🚧
Swift 6 Support
v3 SDKs do not support Swift v6.

CocoaPods

Add the Trustly package to your Podfile

pod 'TrustlySDK'

Swift Package Manager

With your project open in Xcode, choose File > Add Package Dependencies...

Search for "trustly-ios" or paste the package URL below into the search bar.

https://github.com/TrustlyInc/trustly-ios.git

Choose "Add Package".

Manual

Check ios-legacy documentation .

OAuth Configuration

In order to support OAuth login flows, the Trustly Lightbox interacts with the ASWebAuthenticationSession class and in some cases it hands off to the user's mobile banking app directly. In order to support this functionality, you must have at least one url scheme configured in your Info.plist file.

🚧
Deep Link Required
If your app does not already have a defined deep link or URL scheme, you must define one. Without it, users will not be automatically redirected to your app after logging in on a mobile banking app.

More on this later, but the next steps will reference "your app's deep link".

Lightbox Integration

With the configurations above in place, you are ready to integrate the Trustly Lightbox into your iOS app.

👍
Checklist

Define Establish data with a requestSignature

Display the Select Bank Widget

Launch the Lightbox

Handle Callback Events

Note: The examples provided in this guide are based on UIKit.

Define Establish Data with a Request Signature

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 iOS 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 example customer information or unique order identifiers to be included in the merchantReference field. For simplicity in this example it is primarily hardcoded into the view:

import UIKit
import TrustlySDK

@IBOutlet weak var trustly: TrustlyView!
var establishData:Dictionary<AnyHashable,Any>?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        self.establishData = [
          "accessId": YOUR_ACCESS_ID,
          "merchantId": YOUR_MERCHANT_ID,
          "requestSignature": GENERATED_HASH, 
          "description": "transaction description",
          "merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
          "amount": "0.00",
          "paymentType":"Deferred",
          "currency":"USD",
          "metadata.urlScheme":"yourapp://", // your app's deep link
     //   "env": "sandbox",
       ]
    }

NOTE: When developing against the sandbox environment, set the env property to sandbox. When publishing your production application, remove the env property altogether.

See Establish Data for more details on required properties, accepted values and their behaviors.

Display the Select Bank Widget

While it is possible to launch the Trustly Lightbox without use of the Select Bank Widget, Trustly recommends rendering the Select Bank Widget for an optimal user experience. For information on the Select Bank Widget as it relates to the Trustly Lightbox visit Displaying the Bank Widget.

In your application, on the parent view implementation of viewDidLoad call the SDK’s selectBankWidget function to initiate the Select Bank Widget view.

v3 SDK:

@IBOutlet weak var trustly: TrustlyView!
var establishData:Dictionary<AnyHashable,Any>?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        self.establishData = [
          "accessId": YOUR_ACCESS_ID,
          "merchantId": YOUR_MERCHANT_ID,
          "requestSignature": GENERATED_HASH, 
          "description": "transaction description",
          "merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
          "amount": "0.00",
          "paymentType":"Deferred",
          "currency":"USD",
          "metadata.urlScheme":"yourapp://", // your app's deep link
          "metadata.lang":"en_US",
          // "env": "sandbox",
       ]

        self.trustly.selectBankWidget(establishData) { (view, data) in
            if let data = data {
                print("returnParameters:\(data)")
                self.establishData = data
            }
        }
      
    }

v4 SDK:

...

var establishData:Dictionary<AnyHashable,Any>?

override func viewDidLoad() {
      super.viewDidLoad()

      let widgetVC = WidgetViewController(establishData: establishData)
      widgetVC.delegate = self

      widgetVC.view.frame = CGRect(x: 16, y: 220, width: 350, height: 500)
      view.addSubview(widgetVC.view)

}

...

extension YOUR_VIEW_CONTROLLER: TrustlySDKProtocol {
    func onReturn(_ returnParameters: [AnyHashable : Any]) {
        // WILL BE TRIGGERED WHEN LIGHTBOX COMPLETES AUTHENTICATION SUCCESSFULLY.

    }
    
    func onCancel(_ returnParameters: [AnyHashable : Any]) {
        // WILL BE TRIGGERED WHEN LIGHTBOX COMPLETES FAILED AUTHENTICATION.

    }
    
    func onBankSelected(data: [AnyHashable: Any]) {
        // WILL BE TRIGGERED WHEN THE WIDGET RETURN THE SELECTED BANK.
    }
    
    func onExternalUrl(onExternalUrl: TrustlyViewCallback?) {
				// CALLED WHE THE TRUSTLYSDK PANEL MUST OPEN AN EXTERNAL URL
    }
    
    func onChangeListener(_ eventName: String, _ eventDetails: [AnyHashable : Any]) {
        // WILL BE TRIGGERED WHEN THE JAVASCRIPT POST SOME EVENT.
    }
}

...

Now your app will render the Select Bank Widget, allowing a user to select their bank from the widget before proceeding. No transaction data will be created until implementing the establish function in the next step.

Launch the Lightbox

The Lightbox is launched by calling the establish function with the establishData defined above. This function can be called by any button in your app such as a "Checkout" or "Continue" button. For this example we will:

v3 SDK:

class TrustlyLightboxViewController: UIViewController {
    
    var establishData:Dictionary<AnyHashable,Any>?
    var delegate: TrustlyLightboxViewProtocol?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let trustlyLightboxPanel = TrustlyView()
                
        self.view = trustlyLightboxPanel.establish(self.establishData, onReturn: {}, onCancel: {}) 
        
    }
    
}

v4 SDK:

...

var lightboxViewController = LightBoxViewController(establishData: establishData)
lightboxViewController.delegate = self

self.present(lightboxViewController, animated: true)

...

At this point, a user can select a bank from the Select Bank Widget and launch the Lightbox with the provided Establish data.

OAuth Setup and Redirects

In the case Next, add extensions to handle this deep link and trigger a notification to communicate to the Lightbox SDK that a user has returned to your application. This can be done in your AppDelegate or SceneDelegate, or in an extensions file. For example:

extension AppDelegate {

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {

        if url.absoluteString.contains("yourapp:") {
            NotificationCenter.default.post(name: .trustlyCloseWebview, object: nil)
        }
        return true
    }
}


extension Notification.Name{
    static let trustlyCloseWebview = Notification.Name(TrustlyView.trustlyCloseWebview)
}

For a more comprehensive example of this logic, check out the Trustly iOS example app. Now that your app will support OAuth bank redirects, the Lightbox integration is nearly complete. In the next section we'll add handler functions to the onReturn and onCancel callback functions to complete our basic Lightbox implementation and direct users to the success or failure cases in your app.

Handle Lightbox Callback Events

The Trustly Lightbox provides two callback functions to handle terminal user behaviors. When a user successfully creates a bank authorization, the onReturn function will be called. If the user exits the process at any time or the authorization is otherwise unsuccessful, the onCancel function will be called. Find more details regarding these functions at Handling the Redirect.

Define two functions to handle these callbacks and pass them into the onReturn and onCancel parameters of the establish method. Handling the user experience of a cancellation or a successful authorization can be done in many ways. When the authorization is successful, your app can direct the user to the next step on their journey. In the background, your server will also receive an event from Trustly with corresponding data. To simulate a failure scenario and test various error codes, see the testing guide.

Example:

v3 SDK:

var establishData:Dictionary<AnyHashable,Any>?
var amount: String?
var delegate: TrustlyLightboxViewProtocol?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let trustlyLightboxPanel = TrustlyView()
        
        guard let amountText = amount else { return }
        
        self.establishData = [
          "accessId": YOUR_ACCESS_ID,
          "merchantId": YOUR_MERCHANT_ID,
          "requestSignature": GENERATED_HASH, 
          "description": "transaction description",
          "merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
          "amount": "0.00",
          "paymentType":"Deferred",
          "currency":"USD",
          "metadata.lang":"en_US"
       ]
        
          self.view = trustlyLightboxPanel.establish(self.establishData , onReturn: {(trustly, returnParameters)->Void in
                let response = returnParameters as! [String:String]
                self.delegate?.onReturnWithTransactionId(transactionId: response["transactionId"]!, controller: self)
            
            }, onCancel: {(trustly, returnParameters)->Void in
                let response = returnParameters as! [String:String]
                self.delegate?.onCancelWithTransactionId(transactionId: response["transactionId"]!, controller: self)
        })
        
    }

v4 SDK:

...

extension YOUR_VIEW_CONTROLLER: TrustlySDKProtocol {
    func onReturn(_ returnParameters: [AnyHashable : Any]) {
        // WILL BE TRIGGERED WHEN LIGHTBOX COMPLETES AUTHENTICATION SUCCESSFULLY.

    }
    
    func onCancel(_ returnParameters: [AnyHashable : Any]) {
        // WILL BE TRIGGERED WHEN LIGHTBOX COMPLETES FAILED AUTHENTICATION.

    }
    
    func onBankSelected(data: [AnyHashable: Any]) {
        // WILL BE TRIGGERED WHEN THE WIDGET RETURN THE SELECTED BANK.
    }
    
    func onExternalUrl(onExternalUrl: TrustlyViewCallback?) {
				// CALLED WHE THE TRUSTLYSDK PANEL MUST OPEN AN EXTERNAL URL
    }
    
    func onChangeListener(_ eventName: String, _ eventDetails: [AnyHashable : Any]) {
        // WILL BE TRIGGERED WHEN THE JAVASCRIPT POST SOME EVENT.
    }
}

...

Next Steps

Test your mobile app by running the Trustly UI from the sandbox environment and selecting a demo bank to create test transactions. See more on testing and demo banks and additional items:

If you'd like more help with your integration, reach out to your Trustly representative or send your request to [email protected].