iOS

The Trustly Lightbox SDK for iOS allows you to 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, your app must be configured to handle Universal Links so users are automatically returned to your app after authenticating with their bank. See Set up Universal Links for configuration steps.

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.deepLinkUrl":"https://yourdomain.com/trustly-return", // Your Universal 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
var establishData:Dictionary<AnyHashable,Any>?
2
3
override func viewDidLoad() {
4
        super.viewDidLoad()
5
6
        let widgetVC = WidgetViewController(establishData: establishData)
7
        widgetVC.delegate = self
8
9
        widgetVC.view.frame = CGRect(x: 16, y: 220, width: 350, height: 500)
10
        view.addSubview(widgetVC.view)
11
}
12
...
13
14
extension YOUR_VIEW_CONTROLLER: TrustlySDKProtocol {
15
    func onReturn(_ returnParameters: [AnyHashable : Any]) {
16
        // Triggered when lightbox completes authentication successfully.
17
    }
18
    func onCancel(_ returnParameters: [AnyHashable : Any]) {
19
        // Triggered when lightbox completes failed authentication.
20
    }
21
    func onBankSelected(data: [AnyHashable: Any]) {
22
        // Triggered when the widget returns the selected bank.
23
    }
24
    func onExternalUrl(onExternalUrl: TrustlyViewCallback?) {
25
        // Called when the TrustlySDK panel must open an external URL.
26
    }
27
    func onChangeListener(_ eventName: String, _ eventDetails: [AnyHashable : Any]) {
28
        // Triggered when JavaScript posts some event.
29
    }
30
}

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
func launchTrustly() {
2
        let widgetVC = WidgetViewController(establishData: establishData)
3
        widgetVC.delegate = self
4
5
        if let nav = self.navigationController {
6
            nav.pushViewController(widgetVC, animated: true)
7
        } else {
8
            self.present(widgetVC, animated: true)
9
        }
10
}

Handle the return from bank authentication

When the bank redirects back to your app via Universal Link, implement the handler in your SceneDelegate (iOS 13+) or AppDelegate (legacy) to notify the Lightbox SDK that the user has returned.

1
import UIKit
2
3
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
4
5
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
6
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
7
              let incomingURL = userActivity.webpageURL else {
8
            return
9
        }
10
        NotificationCenter.default.post(name: .trustlyCloseWebview, object: nil)
11
    }
12
}
13
14
extension Notification.Name {
15
    static let trustlyCloseWebview = Notification.Name(TrustlyView.trustlyCloseWebview)
16
}

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
...
2
3
extension YOUR_VIEW_CONTROLLER: TrustlySDKProtocol {
4
    func onReturn(_ returnParameters: [AnyHashable : Any]) {
5
        // Triggered when lightbox completes authentication successfully.
6
    }
7
    
8
    func onCancel(_ returnParameters: [AnyHashable : Any]) {
9
        // Triggered when lightbox authentication fails.
10
    }
11
    
12
    func onBankSelected(data: [AnyHashable : Any]) {
13
        // Triggered when the widget returns the selected bank.
14
    }
15
    
16
    func onExternalUrl(onExternalUrl: TrustlyViewCallback?) {
17
        // Called when the TrustlySDK panel must open an external URL.
18
    }
19
    
20
    func onChangeListener(_ eventName: String, _ eventDetails: [AnyHashable : Any]) {
21
        // Triggered when JavaScript posts some event.
22
    }
23
}
24
25
...
26
27
## Set up Universal Links
28
29
[Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/) use standard HTTPS URLs to return users directly to your app after bank authentication. Unlike custom URL schemes, they are verified against your domain — preventing other apps from intercepting them — and fall back to your website if the app isn't installed.
30
31
### Define the associated domains
32
33
Create a JSON file named `apple-app-site-association` and host it at one of the following locations on your server:
34
35
* **Root**: `https://yourdomain.com/apple-app-site-association`
36
* **Subdirectory**: `https://yourdomain.com/.well-known/apple-app-site-association`
37
38
Server requirements:
39
40
* Served over HTTPS.
41
* `Content-Type` header set to `application/json`.
42
* Filename must have no extension.
43
44
```json
45
{
46
  "applinks": {
47
    "apps": [
48
      "ABCDE12345.com.yourcompany.YourApp"
49
    ],
50
    "details": [
51
      {
52
        "appID": "ABCDE12345.com.yourcompany.YourApp",
53
        "paths": [
54
          "/trustly-return",
55
          "*"
56
        ]
57
      }
58
    ]
59
  }
60
}

Verify your server returns the correct Content-Type:

$
curl -I https://yourdomain.com/.well-known/apple-app-site-association

Add the Associated Domains entitlement

1. Open your project in Xcode and select your application target.
2. Go to Signing & Capabilities.
3. Click + Capability and select Associated Domains.
4. Add your domains, prefixed with applinks::

applinks:yourdomain.com
applinks:www.yourdomain.com

Implement the Universal Link handler

iOS delivers the Universal Link to your app via the scene(_:continue:) method in your SceneDelegate. Implement this method to extract the incoming URL and pass it to your routing logic:

1
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
2
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
3
          let incomingURL = userActivity.webpageURL else {
4
        return
5
    }
6
    handleDeepLink(url: incomingURL)
7
}

For apps that support both Universal Links and legacy custom URL schemes during a migration period, see Migrate from custom schemes (iOS) for a unified router pattern that handles both link types through a single navigation flow.

Configure your deep link strategy (optional)

Universal Links function without a fallback. However, Trustly recommends having a default deep link strategy configured for your merchant account. This ensures your application has a consistent fallback behavior if a strategy isn’t explicitly provided within the establishData object in your code.

Because this setup requires internal configuration, you’ll need to contact your Customer Success Manager (CSM) or Trustly Support to enable this fallback for your account.

When you submit your request, you must provide the following information:

• Deep link strategy: Specify deeplink-url.
• Universal Link: Provide your fully qualified domain (for example, https://yourdomain.com/).