iOS

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.

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

If you need help with your integration, contact your Trustly representative or send your request to us.integrations@trustly.com.

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

Prerequisites

• iOS 12 or later
• Xcode 14 or later

Add the Trustly package

Add the Trustly package to your application to enable secure and convenient online bank payments.

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.

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:

1
import UIKit
2
import TrustlySDK
3
4
@IBOutlet weak var trustly: TrustlyView!
5
var establishData:Dictionary<AnyHashable,Any>?
6
    
7
    override func viewDidLoad() {
8
        super.viewDidLoad()
9
        
10
        self.establishData = [
11
          "accessId": YOUR_ACCESS_ID,
12
          "merchantId": YOUR_MERCHANT_ID,
13
          "requestSignature": GENERATED_HASH, 
14
          "description": "transaction description",
15
          "merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
16
          "amount": "0.00",
17
          "paymentType":"Deferred",
18
          "currency":"USD",
19
          "metadata.urlScheme":"yourapp://", // your app's deep link
20
     //   "env": "sandbox",
21
       ]
22
    }

NOTE: When using the sandbox environment, set the env property to sandbox. Before 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 Object.

Display the Select Bank Widget

The Trustly Lightbox can be launched without using 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.

1
@IBOutlet weak var trustly: TrustlyView!
2
var establishData:Dictionary<AnyHashable,Any>?
3
4
override func viewDidLoad() {
5
    super.viewDidLoad()
6
7
    self.establishData = [
8
      "accessId": YOUR_ACCESS_ID,
9
      "merchantId": YOUR_MERCHANT_ID,
10
      "requestSignature": GENERATED_HASH,
11
      "description": "transaction description",
12
      "merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
13
      "amount": "0.00",
14
      "paymentType": "Deferred",
15
      "currency": "USD",
16
      "metadata.urlScheme": "yourapp://",
17
      "metadata.lang": "en_US",
18
      // "env": "sandbox",
19
   ]
20
21
    self.trustly.selectBankWidget(establishData) { (view, data) in
22
        if let data = data {
23
            print("returnParameters:\(data)")
24
            self.establishData = data
25
        }
26
    }
27
}

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:

1
@IBOutlet weak var trustly: TrustlyView!
2
var establishData:Dictionary<AnyHashable,Any>?
3
4
func launchTrustly() {
5
    self.trustly.establish(establishData) { (view, data) in
6
        if let data = data {
7
            print("returnParameters:\(data)")
8
            self.establishData = data
9
        }
10
    }
11
}

Set up OAuth and add redirects

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:

1
extension AppDelegate {
2
3
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {
4
5
        if url.absoluteString.contains("yourapp:") {
6
            NotificationCenter.default.post(name: .trustlyCloseWebview, object: nil)
7
        }
8
        return true
9
    }
10
}
11
12
extension Notification.Name{
13
    static let trustlyCloseWebview = Notification.Name(TrustlyView.trustlyCloseWebview)
14
}

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 Redirect URLs.

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:

1
var establishData:Dictionary<AnyHashable,Any>?
2
var amount: String?
3
var delegate: TrustlyLightboxViewProtocol?
4
5
override func viewDidLoad() {
6
    super.viewDidLoad()
7
    
8
    let trustlyLightboxPanel = TrustlyView()
9
    
10
    guard let amountText = amount else { return }
11
    
12
    self.establishData = [
13
      "accessId": YOUR_ACCESS_ID,
14
      "merchantId": YOUR_MERCHANT_ID,
15
      "requestSignature": GENERATED_HASH,
16
      "description": "transaction description",
17
      "merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
18
      "amount": "0.00",
19
      "paymentType": "Deferred",
20
      "currency": "USD",
21
      "metadata.lang": "en_US"
22
    ]
23
    
24
    self.view = trustlyLightboxPanel.establish(self.establishData , onReturn: {(trustly, returnParameters)->Void in
25
        let response = returnParameters as! [String:String]
26
        self.delegate?.onReturnWithTransactionId(transactionId: response["transactionId"]!, controller: self)
27
    }, onCancel: {(trustly, returnParameters)->Void in
28
        let response = returnParameters as! [String:String]
29
        self.delegate?.onCancelWithTransactionId(transactionId: response["transactionId"]!, controller: self)
30
    })
31
}

Universal Links

Configure Universal Links to ensure users return directly to your application after completing a transaction.

• Set up Universal Links
• Migrate from custom schemes