iOS SDK

Learn how to use the iOS version of our mobile SDK to quickly integrate our Payments product into your app.

🚧

This feature is in private beta and is currently available to a limited number of customers. To join our private beta, contact Client Care.

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

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 iOS SDK supports iOS 13.0 and above.

Payment journey

  1. The user selects Pay By Bank.
  2. Your app creates creates a payment on the backend side.
  3. Your backend integration creates a payment and gets a payment resource back.
  4. Your app gets the payment_id and resource_token back and initialises the SDK.
  5. Your user selects and confirms their bank on the screen of the mobile SDK.
  6. The mobile SDK redirects your user to their bank's website or app.
  7. Your user authorises the payment in their bank's website or app.
  8. 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.Image containing a diagram that shows the payment journey with mobile SDK integration.

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:

  1. Create a payment using the Payments API v3.
  2. Register a redirect_uri from 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:

  1. Download the XCFramework.
  2. Unzip the archive.
  3. Open your app in Xcode.
  4. Select your project file.
  5. In the Target Pane, select your app.
  6. In the General tab, scroll down until you find the Frameworks, Libraries, and Embedded Content section.
  7. Drag and drop the TruelayerPayments framework.
  8. Make sure that the Embed option is set to Embed and Sign.

SwiftPM

To install the SDK using the SwiftPM, follow these steps:

If you're using Xcode 12, do the following:

  1. Open your app in Xcode.
  2. Select File > Swift Packages> Add Package Dependencies.
  3. Enter https://github.com/Truelayer/truelayer-ios-sdk in the search bar and select Enter.
  4. Follow the steps in Xcode to install the SDK.

If you're using Xcode 13, do the following:

  1. Open your app in Xcode.
  2. In the Project Navigator, go to the project.
  3. In the Project panel, select the project.
  4. Go to the Package Dependencies tab.
  5. Select +.
  6. Enter https://github.com/Truelayer/truelayer-ios-sdk in the search bar and select Enter.
  7. Select Add Package.
  8. Follow the steps in Xcode to install the SDK.

Cocoapods

  1. Open your Podfile.
  2. Add the line pod 'TruelayerPayments', '~> 1.0.0' with all your other pods.

Step 2: Start the SDK

The SDK has two methods: start() and processPayments().

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 resourceToken from the backend, it can use the TruelayerPayments SDK to process the payment.

To do so, call processPayment and pass a correctly populated PaymentContext object.

The SDK requires both the paymentId and the resourceToken to process the payment. Also, you can specify how the SDK should presents its ViewControllers, using the presentationStyle property.

Finally, the processPayment method can receive a callback that the SDK uses to return a success if everything went well or a failure 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 resourceToken = payment.resourceToken

            do {
                try TruelayerPayments.Manager.shared.processPayment(
                    context: .init(
                        paymentId: paymentId,
                        token: resourceToken,
                            // Deep Link or Universal Link, this is where the user will be redirected after authorising the payment
                        redirectUri: "myapp://payments_sample",
                       presentationStyle: .present(on: self)
                    ),
                    callback: self?.handlePayment
                )
            } catch {
                // Handle processPayment errors
            }
        }
    }

    func handlePayment(result: Result<TruelayerPayments.Models.PaymentProcessingStep, 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)

Did this page help you?