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.
Set Up
Requirements
Installation
- Download the latest version: Trustly iOS SDK 2.3.1
- Unzip the files
- Add the library to your project. In xcode, "File" > "Add files to..."
- Select the
PayWithMyBank.xcframeworkfile and make sure that "copy items if needed" is checked.
PayWithMyBank references
Future versions beyond 3.x.x may deprecate
PayWithMyBankreferences. For current and previous versions, these references will be supported.
OAuth Configuration
In order to support OAuth login flows, the Trustly Lightbox interacts with the ASWebAuthenticationSession class or in some cases it hands off to the user's mobile banking app directly. In order to support this functionality, you mast 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.
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(PayWithMyBankView.trustlyCloseWebview)
}
Lightbox Integration
With the configurations above in place, you are ready to integrate the Trustly Lightbox into your Android app.
Checklist
- Define Establish data with a
requestSignature- Display the Select Bank Widget
- Launch the Lightbox
- Handle Callback Events
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 Android 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 simplicity in this example it is primarily hardcoded into the view:
@IBOutlet weak var trustly: PayWithMyBankView!
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 environment, set the
envproperty tosandbox. When publishing your production application, remove theenvproperty 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.
@IBOutlet weak var trustly: PayWithMyBankView!
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.lang":"en_US",
// "env": "sandbox",
]
self.trustly.selectBankWidget(establishData) { (view, data) in
if let data = data {
print("returnParameters:\(data)")
self.establishData = data
}
}
}
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:
class TrustlyLightboxViewController: UIViewController {
var establishData:Dictionary<AnyHashable,Any>?
var delegate: TrustlyLightboxViewProtocol?
override func viewDidLoad() {
super.viewDidLoad()
let trustlyLightboxPanel = PayWithMyBankView()
self.view = trustlyLightboxPanel.establish(self.establishData, onReturn: {}, onCancel: {})
}
}
At this point, a user can select a bank from the Select Bank Widget and launch the Lightbox with the provided Establish data. In the next section we'll add handler functions to the onReturn and onCancel callback functions to complete a basic Lightbox implementation.
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 exists 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. At a minimum your application will likely need to retrieve some of the data provided in the onReturn callback and pass it to your server.
Example:
var establishData:Dictionary<AnyHashable,Any>?
var amount: String?
var delegate: TrustlyLightboxViewProtocol?
override func viewDidLoad() {
super.viewDidLoad()
let trustlyLightboxPanel = PayWithMyBankView()
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: {(payWithMyBank, returnParameters)->Void in
let response = returnParameters as! [String:String]
self.delegate?.onReturnWithTransactionId(transactionId: response["transactionId"]!, controller: self)
}, onCancel: {(payWithMyBank, returnParameters)->Void in
let response = returnParameters as! [String:String]
self.delegate?.onCancelWithTransactionId(transactionId: response["transactionId"]!, controller: self)
})
}
Next Steps
Additional items to consider beyond this basic Lightbox implementation are:
- 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 3 months ago