iOS SDK

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 and payment_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.

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:

Manually
With the Swift Package Manager (SwiftPM)
With Cocoapods

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
`primary`	Colour used for action buttons. It’s the main accent colour.
`primaryActionLabel`	Colour used for the action button text.
`primaryForeground`	Colour used for the headings.
`secondaryForeground`	Colour used for the sub heading and body.
`primaryBackground`	Colour used for the background of the content view.
`secondaryBackground`	Colour used for the background of the navigation.
`divider`	Colour used for the table cell dividers.
`border`	Colour used for the image borders.
`errorColor`	Colour used to display the error text.
`alertBackgroundColor`	Colour used to change the background of the alert controllers.
`searchPrimaryColor`	Colour used for the text of the search text.
`searchSecondaryColor`	Colour used for the search placeholder text.
`searchCursorTint`	Colour used for the search cursor.
`searchBackground`	Colour used for the search control background.
`searchClearTint`	Colour used for the clear button.
`textPlaceholderColor`	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)