Create payments or mandates with the React Native SDK
Learn how to install the React Native SDK and process payments and mandates.
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:
- Install the SDK and additional platform-specific configurations.
- Import the SDK and configure its environments.
- Create, process, and get the status of a payment or mandate.
- 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"
}
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
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 areSend
orSignUpPlus
.
For standard payments, usePaymentUseCase.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.
PaymentStatus | Description |
---|---|
AuthorizationRequired | The payment requires authorisation. |
Authorizing | The user is authorizing the payment. |
Authorized | The payment has been authorized by the bank. |
Executed | The payment has been executed. |
Settled | The funds have reached the destination. |
Failed | The payment failed. This can be due to various reasons. |
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.
MandateStatus | Description |
---|---|
AuthorizationRequired | The mandate requires authorisation. |
Authorizing | The user is authorizing the mandate. |
Authorized | The user has authorized the mandate with their bank. |
Revoked | The mandate has been revoked and is no longer valid. |
Failed | The mandate failed. Click here for more information. |
4. Handle the ProcessorResult
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.
PaymentStep | Description |
---|---|
Executed | The bank confirmed the payment or mandate. |
Authorized | The user authorized the payment or mandate with the bank. |
Redirect | The user has been redirected to the bank to authorize the payment or mandate. |
Settled | The funds have reached the destination. |
Wait | The SDK flow is complete, but a decoupled authorisation action is still pending with the user and/or the bank. |
Failure cases
ProcessorResult.FailureReason
contains the reason why a payment failed.
FailureReason | Description |
---|---|
ProcessorContextNotAvailable | The context provided to the SDK is invalid. |
NoInternet | There was an issue while connecting to the internet. Either the user is offline, or the request timed out. |
CommunicationIssue | There was an issue communicating with the server. |
ConnectionSecurityIssue | The token used to make the payment or mandate is not authorized to undergo such an operation. |
PaymentFailed | The payment or mandate is in a failed state. Click here for more information: payments or mandates. |
WaitAbandoned | The user abandoned the payment on the wait screen. |
Unknown | The SDK encountered an unexpected behaviour. |
UserAborted | The user cancelled the payment or mandate. |
Updated 9 days ago
Learn how to style the SDK for iOS and Android so it matches your brand.