Guides
Need Help?In Europe? Go to EU docs
Start typing to search…

iOS

Add the Trustly UI to native iOS apps

The Trustly Lightbox SDK for iOS allows you to quickly build a bank authorization workflow in your iOS app. Integrate the Select Bank Widget or the Trustly Lightbox to retrieve bank authorization data that can be used with other Trustly APIs.

Note: The examples provided here assume you're using UIKit.

📘

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.

💻

Example App

To use an example project for testing and learning, see the Swift iOS Example App in Github.

Prerequisites

Add the Trustly package

CocoaPods

  1. Open your project’s Podfile, or create one if it doesn’t exist.

  2. Add the following line:

    pod 'TrustlySDK'

  3. In Terminal, go to your project folder and run:

    pod install

Swift Package Manager

  1. Open your project in Xcode, and then click File > Add Package Dependencies.

  2. Search for trustly-ios or paste the following URL into the search field:

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

  3. Click Add Package and follow the prompts.

Manual

To install the Trustly package manually, see the ios-legacy documentation .

Set Up OAuth Support (Bank Login)

To support OAuth login flows, the Trustly Lightbox interacts with the ASWebAuthenticationSession class. In some cases it interacts with the customer's mobile banking app directly. To support this functionality, you must have at least one url scheme configured in your Info.plist file. To add a URL scheme, see Defining a custom URL scheme for your app.

🚧

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.

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 your iOS app 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, customer information or unique order identifiers you want included in the merchantReference field. For example:

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 using the sandbox environment, set the env property to sandbox. When publishing your production application, remove the env property.

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

For more information about properties, accepted values, and their behaviors, see Establish Data.

Display the Select Bank Widget

The Trustly Lightbox can be launched without using of the Select Bank Widget. However, Trustly recommends rendering the Select Bank Widget for an optimal customer experience. For information about using the Select Bank Widget with the Trustly Lightbox, see Displaying the Bank Widget.

In your application, on the parent view implementation of viewDidLoad call the Trustly Lightbox SDKselectBankWidget function to initiate the Select Bank Widget view.

The following examples render the Select Bank Widget and then allow a customer to select their bank:

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]) {
        // TRIGGERED WHEN LIGHTBOX COMPLETES AUTHENTICATION SUCCESSFULLY.

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

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

...

Launch the Lightbox

The Lightbox is launched by using the establishData parameter and the establish method. Customers activate the method by selecting a Checkout or a Continue button in your app. For example:

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)

...

Set up OAuth and Add Redirects

You add Swift AppDelegate or SceneDelegate classes or use an extensions file to handle the deep link and trigger a notification to communicate to the Lightbox SDK that a customer has returned to your application. 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, see the Trustly iOS example app.

Add Callback Functions

The Trustly Lightbox provides two callback functions to process terminal customer behaviors. When a customer successfully creates a bank authorization, the onReturn function is called. If the user exits the process at any time, or the authorization is otherwise unsuccessful, the onCancel function is called. For more information about these functions, see Handling the Redirect.

Define two functions to handle these callbacks and pass them into the onReturn and onCancel parameters of the establish method. In the following examples, customer or Trustly app responses activate specific events:

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]) {
        // TRIGGERED WHEN LIGHTBOX COMPLETES AUTHENTICATION SUCCESSFULLY.

    }
    
    func onCancel(_ returnParameters: [AnyHashable : Any]) {
        // TRIGGERED WHEN LIGHTBOX AUTHENTICATION FAILS.

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

...

Next Steps

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

Updated 8 days ago

What’s Next