Our React Native SDK combines all the features of our Android and iOS SDKs into one simple library that you can use in your React Native project. It communicates with the Payments API to make your integration project easier, and presents native payment initiation screens to your users, returning a simple result to your app.

Compatibility

• Xcode 14.x and iOS 14.0 and above.
• Android 7.0 (API level 24) and above.

Payment and mandate authorisation journey

When a customer makes a payment or creates a mandate through your React Native SDK integration:

1. The user selects to pay through an instant bank payment, or to set up a recurring payment mandate.
2. Your backend creates a payment or mandate with TrueLayer and receives an id and resource_token.
   If you include signup_plus in related_products at payment creation, the authorisation flow changes to reflect this.
3. Your app uses the id and resource_token to initialise the SDK.
4. Your user selects and confirms their bank on the provider selection screen through the mobile SDK. If the bank needs additional information from the user, such as IBAN or branch, then the SDK screens ask the user to enter these.
5. For banks that use a redirect flow, 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.
6. Optionally, for banks that use an embedded flow, the mobile SDK collects the user's credentials and handles the strong customer authentication in order to authorise the payment.
7. Once the authorisation is complete, the user is redirected to your return URI. You can then confirm the result to your user.

Payments

Before you start

Register a return URI 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 React Native SDK. Learn more about how to create a payment, and authenticate, and sign your requests (our payment quickstart guide provides an overview).

Software version dependencies

For iOS and Android respectively, the React Native SDK requires a minimum of:

• Xcode 14.x and iOS 14.0
• Android 5.0 (API level 21)

Configuration overview

There are four steps to configuring the React Native SDK to authorise payments:

1. Install the SDK and platform-specific configuration
2. Import the SDK and configure environments
3. Process and check payments
4. Handle the ProcessorResult

1. Install and set up the SDK

You can install the React Native SDK with either Yarn or npm.

To install the SDK with Yarn, run this command:

yarn add rn-truelayer-payments-sdk

To install the SDK with npm, run this command:

npm install rn-truelayer-payments-sdk --save

Additional configuration for iOS

To ensure that the React Native SDK can install new dependencies when needed, you should install Cocoapods.

In your iOS folder, run:

• This command if using the new React Native architecture:
  RCT_NEW_ARCH_ENABLED=1 bundle exec pod install
• This command if using the old React Native architecture:
  bundle exec pod install

Additional configuration for Android

To remove excess LICENSE-MIT files and to be able to run on an Android API level beneath 26, you should enable core library desugaring and update packing options. To do this, update your Android file as follows:

android {
    // this part will enable core library desugaing
    compileOptions {
        coreLibraryDesugaringEnabled true
    }
    
    // this part will remove excess LICENSE-MIT files
    packagingOptions {
        resources {
            pickFirsts += ['META-INF/LICENSE-MIT']
        }
    }
}

dependencies {
    // Add to your projects `build.gradle`.
    // We are currently using following version of desuga libraries
    coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.4"
}

Additional configuration for Expo

In your app.json file, you need to add the following configuration for the expo-build-properties

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 33,
            "targetSdkVersion": 33,
            "buildToolsVersion": "33.0.0",
            "packagingOptions": {
              "exclude": ["META-INF/LICENSE-MIT"]
            }
          },
          "ios": {
            "deploymentTarget": "14.0"
          }
        }
      ]
    ]        
  }
}

The React Native SDK is a wrapper around a native mobile TrueLayer Payments SDK. It is not possible to use it with Expo for web.

It's also not possible to use the SDK within the Expo Go app. To test the SDK, you must build the Android and iOS apps. You can do that by running the following commands:

For Android:

npx expo prebuild
npx expo run:android

For iOS:

npx expo prebuild
npx expo run:ios

2. Import the SDK and configure environments

Once you've installed the SDK, the next step is to import the React Native SDK. Here's an example:

import {
  TrueLayerPaymentsSDKWrapper,
  Environment,
  PaymentUseCase,
  ResultType,
} from "rn-truelayer-payments-sdk";

You can then configure your SDK to work in either the sandbox or production environment by using Environment.Sandbox or Environment.Production respectively:

TrueLayerPaymentsSDKWrapper.configure(Environment.Sandbox).then(
  () => {
    console.log("Configure success");
  },
  (reason) => {
    console.log("Configure failed " + reason);
  }
);

📘

You also use this configuration method to customise the React Native SDK by adding a theme.

3. Process and check payments

Once you've installed and configured the React Native SDK, you can process a payment. To do this, you must have created a payment and have its id.

In this section, learn how to:

• Process a payment
• Handle redirects in the authorisation flow
• Check the status of the payment

Process a payment

Before you can process a payment, you must first make a successful POST request to the /v3/payments endpoint. Then, provide the parameters when you process the payment:

TrueLayerPaymentsSDKWrapper.processPayment({
  paymentId: "", // Your payment ID,
  resourceToken: "", // Your payment token,
  redirectUri: "", // Your redirect URI,
},
// Optional payment preferences
{
	shouldPresentResultScreen: true, // Whether to display the payment result screen.
  preferredCounryCode: GB // The IOS 3166-2 country code, which determines the banks displayed.
}).then((result) => {
  switch (result.type) {
    case ResultType.Success:
      console.log(`processPayment success at step: ${result.step}`);
      break;
    case ResultType.Failure:
      console.log(`processPayment failure reason: ${result.reason}`);
      break;
  }
});

The mandatory parameters in PaymentContext are:

• paymentId: The payment id received after you created the payment.
• resourceToken: The resource_token received after you created the payment.
• redirectUri: Where the user should be redirected to after the authorization flow is completed outside of your app (bank website, HPP). This is usually your app's redirect URI, which you should add in Console,

The optional parameters in PaymentPreferences are:

• shouldPresentResultScreen: A Boolean parameter that determines whether the payment result screen displays.
• preferredCountryCode: You can use this with a two-character country code to specify which country to display payment providers for.
  If the code is invalid, or the country has no providers, the value defaults to the user's browser locale.

Handle redirects in the authorisation flow

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

In your activity that launches when a deep link is triggered, you can fetch the redirect parameters from the url which will include the payment_id.

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 result screen, you can use the success or error callback to render a screen for your user when they return to your app.

AIS and PIS flow

To make the user experience simpler, you can give your user the option of creating an additional Data connection when they consent to a payment. This flow appears for some German banks when your user would need to input an IBAN at the authorisation stage.

When your user logs into their bank, a screen displays with a list of IBANs associated with their credentials. They can then select the IBAN that they want to pay with, without having to input it manually.

Check payment status

The React Native SDK offers the following method to check the status of a payment. You should consider this the best source of truth for the payment's status.

TrueLayerPaymentsSDKWrapper.paymentStatus({
  paymentId: "", // Your payment ID,
  resourceToken: "", // Your payment token
}).then((result) => {
  switch (result.type) {
    case ResultType.Success:
      console.log(`paymentStatus success with status: ${result.status}`);
      break;
    case ResultType.Failure:
      console.log(
        `paymentStatus failed with the following reason: ${result.failure}`
      );
      break;
  }
});

This is a list of the different payment statuses the SDK can return. Learn more about payment statuses.

4. Handle the ProcessorResult

The processPayment method in the React Native SDK returns a ProcessorResult type.

Success cases

ProcessorResult.PaymentStep contains different success results that are part of the payment flow.

Failure cases

ProcessorResult.FailureReason contains the reason why a payment failed. These reasons are shared across payments and mandates.

Display the payment result screen

The payment result screen is enabled by default. To display it to your user after the payment is authorised (or fails) you must relaunch the SDK using the same PaymentContext you used when you first processed the payment.

Possible payment results and callbacks

When your user sees the payment result screen, you receive a ResultShown callback. This applies for both successful and failed payments, and contains the following properties, which explain the result the user saw:

Mandates

Before you start

Register a return URI 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 mandate journey.

You also need an integration that can create a mandate, and get a mandate id, to start the React Native SDK. Learn more about how to create a mandate, and authenticate, and sign your requests.

Software version dependencies

For iOS and Android respectively, the React Native SDK requires a minimum of:

• Xcode 14.x and iOS 14.0 and above.
• Android 7.0 (API level 24) and above.

Configuration overview

There are four steps to configuring the React Native SDK to authorise mandates:

1. Install the SDK and platform-specific configuration
2. Import the SDK and configure environments
3. Process and check mandates
4. Handle the ProcessorResult

1. Install and set up the SDK

You can install the React Native SDK with either Yarn or npm.

To install the SDK with Yarn, run this command:

yarn add rn-truelayer-payments-sdk

To install the SDK with npm, run this command:

npm install rn-truelayer-payments-sdk --save

Additional configuration for iOS

To ensure that the React Native SDK can install new dependencies when needed, you should install Cocoapods.

In your iOS folder, run:

• This command if using the new React Native architecture:
  RCT_NEW_ARCH_ENABLED=1 bundle exec pod install
• This command if using the old React Native architecture:
  bundle exec pod install

Additional configuration for Android

To remove excess LICENSE-MIT files and to be able to run on an Android API level beneath 26, you should enable core library desugaring and update packing options. To do this, update your Android file as follows:

android {
    // this part will enable core library desugaing
    compileOptions {
        coreLibraryDesugaringEnabled true
    }
    
    // this part will remove excess LICENSE-MIT files
    packagingOptions {
        resources {
            pickFirsts += ['META-INF/LICENSE-MIT']
        }
    }
}

dependencies {
    // Add to your projects `build.gradle`.
    // We are currently using following version of desuga libraries
    coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.4"
}

Additional configuration for Expo

In your app.json file, you need to add the following configuration for the expo-build-properties

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 33,
            "targetSdkVersion": 33,
            "buildToolsVersion": "33.0.0",
            "packagingOptions": {
              "exclude": ["META-INF/LICENSE-MIT"]
            }
          },
          "ios": {
            "deploymentTarget": "14.0"
          }
        }
      ]
    ]        
  }
}

The React Native SDK is a wrapper around a native mobile TrueLayer Payments SDK. It is not possible to use it with Expo for web.

It's also not possible to use the SDK within the Expo Go app. To test the SDK, you must build the Android and iOS apps. You can do that by running the following commands:

For Android:

npx expo prebuild
npx expo run:android

For iOS:

npx expo prebuild
npx expo run:ios

2. Import the SDK and configure environments

Once you've installed the SDK, the next step is to import the React Native SDK. Here's an example:

import {
  TrueLayerPaymentsSDKWrapper,
  Environment,
  PaymentUseCase,
  ResultType,
} from "rn-truelayer-payments-sdk";

You can then configure your SDK to work in either the sandbox or production environment by using Environment.Sandbox or Environment.Production respectively:

TrueLayerPaymentsSDKWrapper.configure(Environment.Sandbox).then(
  () => {
    console.log("Configure success");
  },
  (reason) => {
    console.log("Configure failed " + reason);
  }
);

📘

You also use this configuration method to customise the React Native SDK by adding a theme.

3. Process and check mandates

Once you've installed and configured the React Native SDK, you can process a VRP mandate. In order to do this, you must have created a mandate and have its id.

In this section, learn how to:

• Process a mandate
• Handle redirects in the authorisation flow
• Check the status of the mandate

Process a mandate

Before you can process a mandate, you must first make a successful POST request to the /v3/mandates endpoint. After that, you can process the mandate:

TrueLayerPaymentsSDKWrapper.processMandate({
  mandateId: "", // Your mandate ID,
  resourceToken: "", // Your mandate token,
  redirectUri: "", // Your redirect URI,
},
// Optional mandate preferences
{
	shouldPresentResultScreen: true, // Whether to display the mandate result screen.
  preferredCounryCode: GB // The IOS 3166-2 country code, which determines the banks displayed.
}).then((result) => {
  switch (result.type) {
    case ResultType.Success:
      console.log(`processMandate success at step: ${result.step}`);
      break;
    case ResultType.Failure:
      console.log(`processMandate failure reason: ${result.reason}`);
      break;
  }
});

The mandatory parameters in MandateContext are:

• mandateId: The mandate id received after you created the mandate.
• resourceToken: The resource_token received after you created the mandate.
• redirectUri: Where the user should be redirected to after the authorization flow is completed outside of your app (bank website, HPP). This is usually your app's redirect URI, which you should add in Console,

The optional parameters in MandatePreferences are:

• shouldPresentResultScreen: A Boolean parameter that determines whether the mandate result screen displays.
• preferredCountryCode: You can use this with a two-character country code to specify which country to display banking providers for.
  If the code is invalid, or the country has no providers, the value defaults to the user's browser locale.

Handle redirects in the authorisation flow

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

In your activity that launches when a deep link is triggered, you can fetch the redirect parameters from the url which will include the mandate_id.

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 mandate result screen, which displays the result of the mandate and advises the user on what to do in case of a failed mandate. If you disable the mandate result screen, you can use the success or error callback to render a screen for your user when they return to your app.

Check mandate status

The React Native SDK offers the following method to check the status of a mandate. You should consider this the best source of truth for the mandate's status.

TrueLayerPaymentsSDKWrapper.mandateStatus({
  mandateId: "", // Your mandate identifier,
  resourceToken: "", // Your mandate resource token,
}).then((result) => {
  switch (result.type) {
    case ResultType.Success:
      console.log(`mandateStatus success: ${result.status}`);
      break;
    case ResultType.Failure:
      console.log(
        `mandateStatus failed with the following reason: ${result.failure}`
      );
      break;
  }
});

This is a list of the different mandate statuses the SDK can return. Learn more about mandate statuses.

4. Handle the ProcessorResult

The processMandate method in the React Native SDK returns a ProcessorResult type.

Success cases

ProcessorResult.PaymentStep contains different success results that are part of the mandate flow (it isn't called MandateStep).

Failure cases

ProcessorResult.FailureReason contains the reason why a mandate failed. These reasons are shared across payments and mandates.

Display the mandate result screen

The mandate result screen is enabled by default. To display it to your user after the mandate is authorised (or fails) you must relaunch the SDK using the same MandateContext you used when you first processed the mandate.

Possible mandate results and callbacks

When your user sees the mandate result screen, you receive a ResultShown callback. This applies for both successful and failed mandates, and contains the following properties, which explain the result the user saw: