iOS
Quickstart guide for adding 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. 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
Installation
Legacy Versions
v4 SDKs deprecate
v3
references.v3 SDKs deprecated
PayWithMyBank
references. If your app previously used version 2, update these references toTrustly
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 tosandbox
. When publishing your production application, remove theenv
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:
- Testing and demo banks
- Handling Errors in the Lightbox
- Customizing content strings in the Lightbox
- Branding & Experience guidance
If you'd like more help with your integration, reach out to your Trustly representative or send your request to [email protected].
Updated 4 days ago