Create payments or mandates with the React Native SDK

Prerequisites

Before you can create payments or mandates with the React Native SDK, ensure you meet these prerequisites.

Configure Console

Before you can use the React Native SDK, you need to register a return URI in Console. Your user is redirected back to your return URI, typically your website or application, at the end of the payment or mandate journey.

Create a payment

To test or use the React Native SDK, you need a payment or mandate id and resource_token. This means you need to develop a back end which can create payments or mandates. Creating a payment also requires request signing and idempotency).

Software versions

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 with the Payments API v3:

1. Install the SDK and additional platform-specific configurations.
2. Import the SDK and configure its environments.
3. Create, process, and get the status of a payment or mandate.
4. Handle the ProcessorResult.

1. Install 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:1.2.2"
}

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 is 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 or mandate. In order to do this, you must have created a payment or mandate and have its id.

In this section, learn how to:

• Process a payment
• Process a mandate
• Handle the ProcessorResult of the payment or mandate

Process a payment

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

TrueLayerPaymentsSDKWrapper.processPayment({
  paymentId: "", // Your payment ID,
  resourceToken: "", // Your payment token,
  redirectUri: "", // Your return URI,
}).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;
  }
});

For paymentId and resourceToken, provide the payment id and resource_token returned from the earlier payment creation request.

For redirectUri, provide the URI you want to redirect the user to after the payment, which you should also add in Console.

You can change the parameters of PaymentPreferences to change the payment flow:

• 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.
• paymentUseCase: This is the wording the SDK displays to the user when they send a payment. Possible values are Send or SignUpPlus.
  For standard payments, use PaymentUseCase.Send, the default value.

Check payment status

The React Native SDK offers the following method to check the status of a payment.

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.

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 identifier,
  resourceToken: "", // Your mandate resource token,
  redirectUri: "", // Your return URI,
}).then((result) => {
  switch (result.type) {
    case ResultType.Success:
      console.log(`processMandate success at step: ${result.step}`);
      break;
    case ResultType.Failure:
      console.log(`processMandate failed with reason: ${result.reason}`);
      break;
  }
});

For mandateId and resourceToken, provide the mandate id and resource_token returned from the earlier mandate creation request.

For redirectUri, provide the URI you want to redirect the user to after mandate creation, which you should also add in Console.

You can change the parameter in MandatePreferences to change the payment flow:

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

Check mandate status

The React Native SDK offers the following method to check the status of a mandate.

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 payment statuses the SDK can return. Learn more about mandate statuses.

4. Handle the ProcessorResult

The processPayment and processMandate methods in the React Native SDK return 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.