> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://amer.developers.trustly.com/llms.txt.
> For full documentation content, see https://amer.developers.trustly.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server.

# 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](https://github.com/TrustlyInc/trustly-ios-example) in GitHub.

If you need help with your integration, contact your Trustly representative or send your request to <a href="mailto:us.integrations@trustly.com">[us.integrations@trustly.com](mailto:us.integrations@trustly.com)</a>.

*Note*: The examples provided here assume you're using [UIKit](https://developer.apple.com/documentation/uikit).

v3 SDKs deprecated `PayWithMyBank` references. If your app previously used {' '}
[version 2](ios-deprecated), update these references from `PayWithMyBank` to `Trustly` before you update to a v3 SDK.

v3 SDKS do not support Swift v6.

### Prerequisites

* [iOS 12](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-12-release-notes) or later
* [Xcode 14](https://developer.apple.com/documentation/xcode-release-notes/xcode-14-release-notes) 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:

   ```text
   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](/sdks/mobile/i-os) .

### Set Up OAuth support (Bank Login)

To support OAuth login flows, the Trustly Lightbox interacts with the [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/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](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app).

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:

```swift
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`. Before publishing your production application, remove the `env` property.

For more information about generating a `requestSignature`, see [Securing Requests](/integrate/api-fundamentals/secure-requests-and-signature-validation).

For more information about properties, accepted values, and their behaviors, see [Establish Data Object](/integrate/core-concepts/the-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](/sdks#select-bank-widget).

In your application, on the parent view implementation of `viewDidLoad` call the Trustly Lightbox SDK`selectBankWidget` 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.

```swift title="SDK (V3)"
@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://",
      "metadata.lang": "en_US",
      // "env": "sandbox",
   ]

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

```swift title="SDK (V4)"
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 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.
    }
}
```

### 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:

```swift title="SDK (V3)"
@IBOutlet weak var trustly: TrustlyView!
var establishData:Dictionary<AnyHashable,Any>?

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

```swift title="SDK (V4)"
func launchTrustly() {
        let widgetVC = WidgetViewController(establishData: establishData)
        widgetVC.delegate = self

        if let nav = self.navigationController {
            nav.pushViewController(widgetVC, animated: true)
        } else {
            self.present(widgetVC, animated: true)
        }
}
```

### 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:

```swift
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](https://github.com/TrustlyInc/trustly-ios-example).

### 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](/integrate/core-concepts/redirect-urls-and-return-flow).

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:

```swift title="SDK (V3)"
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)
    })
}
```

```swift title="SDK (V4)"
...

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

...
```

### Universal Links

Configure [Universal Links](/sdks/mobile/android#/app-links) to ensure users return directly to your application after completing a transaction.

* [Set up Universal Links](/sdks/mobile/i-os/set-up-universal-links)
* [Migrate from custom schemes](/sdks/mobile/android/migrate-from-custom-schemes-android)