iOS SDK
Learn how to use the iOS version of our mobile SDK to quickly integrate our Payments product into your app.
With the TrueLayer SDK for iOS, you can quickly add open banking payments to your app. Our iOS SDK integrates with TrueLayer's Payments API, making it simple to get up and running.


Image showing what the native screens look like on an iOS device. There are two screenshots in the image, one shows the bank selection screen and the other shows the payment confirmation screen.
The SDK presents native screens that allow your users to select their bank and consent to the payment. The user is then redirected to their banking app or website to authorise the payment. It also handles the network requests and errors, and gives you options to customise the user interface.
Compatibility
The SDK is currently optimised for the UK, Ireland, Spain, France, the Netherlands and Lithuania. Beta testers can also use the iOS SDK for banks in Portugal. The user interface can be displayed in English, Spanish, French, German, Dutch, Portuguese and Lithuanian.
At a minimum, the SDK requires:
- iOS 13.0
- Xcode 13
- Swift 5.5
Payment journey
- The user selects Pay By Bank.
- Your app creates a payment on the backend side.
- Your backend integration creates a payment and gets a payment resource back.
- Your app gets the
payment_id
andpayment_token
back and initialises the SDK. - Your user selects and confirms their bank on the screen of the mobile SDK.
- The mobile SDK redirects your user to their bank's website or app.
- Your user authorises the payment in their bank's website or app.
- Once the authorisation is complete, the bank redirects the user to your
redirect_url
.


Image containing a diagram that shows the payment journey with mobile SDK integration.
Before you begin
Before you can use the SDK, you have to:
- Create a payment using the Payments API v3.
- Register a
redirect_uri
in your console. Your user will be redirected back to your website or application at the end of the payment journey.
Step 1: Install the SDK
The SDK is released as a compiled binary in the form of an XCFramework artefact. There are three ways to install:
Manual Installation
To install the SDK manually, follow these steps:
- Download the XCFramework.
- Unzip the archive.
- Open your app in Xcode.
- Select your project file.
- In the Target Pane, select your app.
- In the General tab, scroll down until you find the Frameworks, Libraries, and Embedded Content section.
- Drag and drop the TruelayerPaymentsSDK framework.
- Make sure that the Embed option is set to Embed and Sign.
SwiftPM
- Open your app in Xcode.
- In the Project Navigator, go to the project.
- In the Project panel, select the project.
- Go to the Package Dependencies tab.
- Select +.
- Enter
https://github.com/Truelayer/truelayer-ios-sdk
in the search bar and select Enter. - Select Add Package.
- Follow the steps in Xcode to install the SDK.
Step 2: Start the SDK
The SDK has two methods: start()
and processPayment()
.
The interface that exposes all functions is the TruelayerPaymentsManager
protocol. You can obtain a reference to an instance that implements the protocol by using the TruelayerPayments.Manager.shared
instance.
To use the SDK, you have to invoke its start()
method. The start()
method accepts two parameters:
- An environment, which can be .production or .sandbox. The environment determines which TrueLayer backend your app will use to process the payment.
- An optional
UIStyle
object, which is used to provide a customised payment experience in your app. For example, you can match your app's main colours with this object. If not provided, the app will use system colours. See customisation for more detail on how to set the right style for your app.
You should initialize the SDK inside your AppDelegate
, SceneDelegate
, or any other container to manage your dependencies.
The following example shows how this can be done using the SceneDelegate
:
import TrueLayerPaymentsSDK
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
guard let windowScene = scene as? UIWindowScene else { return }
do {
try TruelayerPayments.Manager.shared.start(environment: .production)
} catch {
// Handle the TruelayerPayments.Error
}
}
// Other UIWindowSceneDelegate method implementation
}
As you can see, the start()
method may throw a TrueLayerPayments.Error
if something goes wrong with the initialisation.
Step 3: Process a payment
Once your app has obtained the paymentId
and the paymentToken
from the backend, it can use the TrueLayerPayments
SDK to process the payment.
To do so, call processPayment
and pass a correctly populated Context
object.
The SDK requires both a paymentId
and a resourceToken
(the id
and resource_token
from Create Payment respectively) in order to process the payment. Also, you can specify how the SDK should present its ViewControllers
, using the presentationStyle
parameter.
Finally, the processPayment
method can receive a callback that the SDK uses to return a Result
- a .success
containing a PaymentProcessingStep
if everything went well, or a .failure
with a TrueLayerPayments.Error
if something went wrong.
import TrueLayerPaymentsSDK
class ProductViewController: UIViewController {
func processPayment() {
// This function will invoke the backend to authenticate the app and create the payment in the truelayer backend
createPayment(for: product) { [weak self] payment in
let paymentId = payment.id
let paymentToken = payment.paymentToken
do {
try TrueLayerPayments.Manager.shared.processPayment(
context: .init(
paymentId: paymentId,
resourceToken: paymentToken,
// Deep Link or Universal Link, this is where the user will be redirected after authorising the payment
endOfFlowRedirectURI: "myapp://payments_sample",
presentationStyle: .present(on: self)
),
callback: self?.handlePayment
)
} catch {
// Handle `processPayment` errors
}
}
}
func handlePayment(result: Result<TrueLayerPaymentsSDK.TrueLayerPayments.Models.PaymentProcessingStep, TrueLayerPaymentsSDK.TrueLayerPayments.Error>) {
// Handle the result
}
}
Customise colours
Our iOS SDK uses a set of colour parameters that define the style of the user interface.
Parameter | Description |
---|---|
| Colour used for action buttons. It’s the main accent colour. |
| Colour used for the action button text. |
| Colour used for the headings. |
| Colour used for the sub heading and body. |
| Colour used for the background of the content view. |
| Colour used for the background of the navigation. |
| Colour used for the table cell dividers. |
| Colour used for the image borders. |
| Colour used to display the error text. |
| Colour used to change the background of the alert controllers. |
| Colour used for the text of the search text. |
| Colour used for the search placeholder text. |
| Colour used for the search cursor. |
| Colour used for the search control background. |
| Colour used for the clear button. |
| Colour used for the placeholder in the text fields. |
The SDK comes with a default style. You can customise individual properties using the UIStyle
structure. For example:
let viewStyle: UIStyle = UIStyle(primary: .red)
If you specify a single colour, as in the first example above, then that colour is used for all of the appearances. The SDK works with colours loaded from a resource catalog as well.
Our mobile SDK supports dark mode. It exports a convenience init
to create a UIColor
that supports both the light and dark appearances.
let blueOnBlack = UIColor(lightAppearance: UIColor.systemBlue,
darkAppearance: UIColor.black)
Updated 6 days ago