Authorise payments with the iOS SDK

Learn how to install and set up the SDK so your users can authorise payments.

If you have an integration that can create a payment and get the associated id, you can use the iOS SDK to authorise it.

Before you start

Register a redirect URL in Console. Go to Console > Settings > Allowed redirect URIs to do this. Your user is redirected back to your redirect URL, typically your website or application, at the end of the payment journey.

You also need an integration that can create a payment, and get a payment id, to start the iOS SDK. Learn more about how to create a payment, and authenticate, and sign your requests (our payment quickstart guide provides an overview).

Configuration overview for payments with the iOS SDK

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

  1. Install the SDK
  2. Start the SDK
  3. Process the payment authorisation
  4. Handle the authorisation result
  5. Display the payment result screen

1. Install the SDK

There are two different methods you can use to install the iOS SDK. The Swift Package Manager or Cocoapods.

Install the SDK with Swift Package Manager

The SDK is released as a compiled binary in the form of a series of XCFrameworks artefacts.

To 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 in the search bar and select Enter.
  7. Select Add Package.
  8. Follow the steps in Xcode to install the SDK.

Install the SDK with CocoaPods

To install the SDK through CocoaPods, specify TrueLayerPaymentsSDK in your Podfile:

pod 'TrueLayerPaymentsSDK

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

3. Process the payment authorisation

Once your app has obtained the payment identifier (payment id) and the token (access_token)from the backend, it can use the SDK to process the payment. This is an example of how to process a payment in Swift:

  context: TrueLayer.Payments.Models.SinglePayment.Context(
    identifier: // Your payment ID,
    token: // Your resource token,
    redirectURL: // Your redirect URL
    preferences: // Your possible preferences like type of presentation and country code.
  )) { processResult in
    switch processResult.result {
      case .success(let success):
        // Handle `TrueLayer.Payments.Models.SinglePayment.State`.

      case .failure(let failure):
        // Handle `TrueLayer.Payments.Models.SinglePayment.Error`.
    // Handle `resultShown`.

Payment parameters

These are the parameters used above when you process the payment:

  • identifier: The payment id retrieved from your backend.
  • token: The payment access_token retrieved from your backend.
  • redirectURL: The destination where the user should be redirected once the authorisation flow is done outside of the app (bank website, HPP). This is usually your app's redirect URI. set in Console.
  • preferences The preferences parameter enables you to customise the authorisation flow. It contains the following options:
    • presentationStyle: Determines how the SDK should be presented.
    • preferredCountryCode: The preferred country to use when displaying the providers. If the country is invalid, or does not include any providers, the value will fallback to the user's locale.
      shouldShowResultScreen: Whether the TrueLayer SDK should show the payment result screen. See the display the payment result screen section below.
    • maximumResultScreenTimeout: The maximum timeout for refreshing the payment result screen. See the display the payment result screen section below.

When the user is redirected back to your app from their bank app or website, we recommend that you re-invoke processSinglePayment(...) with the same Context. This is because some banks require further input from the user, which the SDK can present.

4. Handle redirects and display the authorisation result

The flow for the authorisation through the iOS SDK where the user is sent to their bank to authorise the payment, then redirected to the Client App.

The flow for the authorisation through the iOS SDK where the user is sent to their bank to authorise the payment, then redirected to the Client App.

Once the redirects are complete, you receive a success or error callback, which renders in the payment result screen.

Handle redirects from the provider

At the end of a redirect flow the bank app will relaunch your app with the return URI you specified in Console.

In your application fetch the redirect parameters. These must include the payment id (or identifier in the SDK). For more information on handling deep links, follow the iOS documentation here and here.

Whenever you are redirected to your app, you should reinvoke the SDK, until you receive a success or error callback.

By default the SDK offers a payment result screen, which displays the result of the payment and advises the user on what to do in case of a failed payment. If you disable the payment result screen, a noneShown result is returned, you can use the success or error callback to render a screen for your user when they return to your app.

We also recommend that you check the payment status to confirm the result of a payment.

Payment success results

The SDK returns the following results for TrueLayer.Payments.Models.SinglePayment.State if a payment is successful or in progress:

TrueLayer.Payments.Models.SinglePayment.State valueDescription
.executedThe payment has been sent to the bank to complete.
.authorizedThe user authorised the payment with the bank.
.redirectThe user has been redirected to the bank to authorise the payment.
.settledThe funds have reached the beneficiary account.
.waitThe SDK flow is complete, but a decoupled authorisation action is still pending with the user and/or the bank.

Payment failure results

The SDK returns the following results for TrueLayer.Payments.Models.SinglePayment.Error if payment authorisation has failed for any reason.

Expand to see all payment failure results
TrueLayer.Payments.Models.SinglePayment.Error valueDescription
.authorizationFailedThe user could not authorise the payment with their bank.
.connectionIssuesThere was an issue while connecting to the internet.
.genericA unexpected error, the error will be passed as a String parameter.
.invalidTokenThe token used to make the payment doesn't have the necessary scopes).
.invalidRedirectURIThe redirect URI passed to the SDK is invalid.
.paymentExpiredThe user took too long to authorise the payment so it expired.
.paymentNotFoundThe requested payment was not found.
.paymentRejectedThe payment was rejected by the bank.
.providerOfflineThe pre-selected provider was offline.
.sdkNotConfiguredThe SDK configure method has not been called before using it.
.serverErrorThe server encountered an error while processing the answer.
.blockedThe payment has been blocked due to a regulatory requirement. This may happen if the PSU fails a sanctions check.
.invalidAccountDetailsThe payment failed because either the creditor's or debtor's account details were invalid.
.invalidAccountHolderNameThe payment failed because the account holder's name details were invalid.
.invalidCredentialsThe banking credentials provided by the PSU to log into their bank were incorrect.
.invalidRemitterAccountThe account details of the remitter bank account provided during the payment flow were incorrect.
.invalidRequestThe payment failed due to invalid data in the request.
.invalidSortCodeThe payment failed due to an invalid sort code being provided.
.insufficientFundsThe PSU did not have the required balance in their account to complete this payment.
.notAuthorizedThe PSU cancelled the payment or wasn't able to successfully authenticate on the provider's UI.
.paymentLimitExceededThe PSU's payment limit amount with their bank was breached.
.providerErrorThe provider has unexpectedly failed when creating the payment.
.providerExpiredThe payment failed because the token or exchange code used to communicate with the bank expired.
.providerRejectedThe provider rejected the payment.
.unknownErrorThe payment failed for an unknown reason on the server side.
.userCanceledAtProviderThe payment failed because the user cancelled the authorisation during the payment flow.
.unexpectedBehaviorThe SDK encountered an unexpected behaviour.
.userCanceledThe user canceled the payment.

Check the status of a payment

You can use the following method in the iOS SDK to get the current status of a payment:

func paymentStatus(
) async throws -> TrueLayer.Payments.Models.SinglePayment.Status

These are the different payment statuses the SDK can return for TrueLayer.Payments.Models.SinglePayment.Status:

Status returned in TrueLayer.Payments.Models.SinglePayment.StatusDescription
.authorizationRequiredThe payment requires authorisation by the user making the payment.
.authorizingThe user is currently authorising the payment.
.authorizedThe user has authorised the payment with their bank.
.executedThe payment has been executed and sent to the bank for completion.
.settledThe funds have reached the beneficiary account.
.failedThe payment failed. This can be due to various reasons, explained in the Error object.

5. Display the payment result screen

We recommend that you display the payment result screen to your customers (learn more about the payment result screen). The payment results screen shows your user the result of the payment. If it fails, it recommends the appropriate action for them to take to resolve the problem.

Payment result screen configuration

Configuration options for the payment result screen are within the Preferences object when you begin to process the payment.

To enable the payment result screen in the iOS SDK, ensure that the shouldShowResultScreen within the Preferences object retains its default value of true. This ensures that the iOS SDK displays the result of a payment at the end of the authorization flow.

This screen automatically refreshes until the payment is creditable, or until a maximum timeout is reached. You can reduce the duration until the timeout by providing a value for maximumResultScreenTimeout within Preferences. By default, this timeout is 10 seconds, and cannot be set longer as the SDK uses 10s if you pass a greater value.