Payments and mandates with the iOS SDK

iOS SDK introduction

With the TrueLayer SDK for iOS, you can quickly add open banking payments or mandates to your app. Our iOS SDK integrates with TrueLayer's Payments API, making it simple to get up and running.

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, France, Germany, Spain, the Netherlands, and Lithuania. Beta testers can also use the iOS SDK for banks in Austria, Belgium, Finland, Poland and Portugal. The user interface can be displayed in English, Spanish, French, German, Dutch, Portuguese, Finnish, Polish and Lithuanian.

At a minimum, the SDK requires:

• iOS 13.0
• Xcode 13
• Swift 5.6

Payment journey

1. The user selects Pay By Bank.
2. Your app 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 payment_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.

Create a payment or mandate with the iOS SDK

📘

Differences between configuring payments and mandates

The integration process for payments and mandates with the iOS SDK is largely the same. Where applicable, code blocks on this page have an adjusted version for each of them.

Prerequisites

Before you can use the SDK, you'll need to register a redirect_uri in Console. Your user is redirected back to your redriect_uri, typically your website or application, at the end of the payment or mandate journey.

Configuration overview

There are four steps to configuring the iOS SDK with the Payments API v3:

1. Install the SDK.
2. Start the SDK.
3. Process a payment
4. Check the result.

1. Install the SDK

The SDK is released as a compiled binary in the form of a series of XCFrameworks artefact. You can install the SDK using Swift Package Manager:

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.

2. Start the SDK

The SDK has two methods: configure(environment:visualSettings:) and processPayment(context:then:), which are used to invoke the SDK and process payments respectively.

The interface that exposes all functions can be accessed through its singleton TrueLayer.Payments.manager.

To use the SDK, you have to invoke its configure(environment:visualSettings:) method. This method should be invoked once.

You also need to specify the environment to process payments in: .production or .sandbox. The environment determines which TrueLayer backend your app will use to process the payment.

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 }
    
    TrueLayer.Payments.manager.configure(environment: .sandbox)
  }
}

3. Process a payment

Once your app has obtained the paymentId and the paymentToken from the backend, it can use the SDK to process the payment.

To do so, call processPayment(context:then:) and pass a correctly populated Context object.

The SDK requires both a paymentIdentifier 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 TrueLayer.Payments.Result. The callback can be:

• .success, containing TrueLayer.Payments.PaymentState, if the payment succeeded.
• .failure, containing TrueLayer.Payments.Error if the payment failed.

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
      TrueLayer.Payments.manager.processPayment(
        context: TrueLayer.Payments.Models.Payment.Context(
          paymentIdentifier: // Your payment ID,
          resourceToken: // Your resource token,
          redirectURL: // Your redirect URL,
          presentationStyle: .present(on: yourViewController, style: .automatic)
        )) { result in
          switch result {
            case .success(let authorizationFlowResult):
              // Handle `TrueLayer.Payments.PaymentState`.
              
            case .failure(let error):
              // Handle `TrueLayer.Payments.Error`. 
          }
        }
    }
  }
}

4. Check the result

Generally, single payments provide an output immediately. However, for various reasons it sometimes might take some time. Such reasons include the need for the user to complete an action on their bank app or website.

The SDK provides a function that returns the status of a payment when given the payment identifier and security token.

func paymentStatus(paymentIdentifier:String,resourceToken:String) async throws