React Native Mobile SDK

Integration Steps

Complete the following steps to successfully integrate the Pine Labs Online React Native Mobile SDK.

Prerequisites
Integrate APIs in Your Backend
SDK Installation and Initialization
Handle Payments
Manage Transactions

❗️ Security Best Practices:

Ensure you store your client_id and client_secret in your Backend securely.

Integrate our APIs on your backend system.

We strictly recommend not to call our APIs from the frontend.

Failure to adhere to the above guidelines may result in legal implications. In such cases, you will be held responsible for any damage or loss arising from non-compliance.

1. Prerequisites

Before integrating the SDK, ensure your React Native project meets the following requirements:

Requirement	Version
React Native	`0.73` or later
React	`18` or later
Node.js	`18` or later
Android	Android `8.0`, API `26` or later
Android compileSdk	API `34` or later
Java Compatibility	`17`
Kotlin	`1.9` or later
iOS Deployment Target	iOS `13.0` or later
Xcode	`15.0` or later
CocoaPods	`1.12` or later

Supported Platforms

Platform	Supported
Android (phone/tablet)	✅
iOS (iPhone/iPad)	✅
Web	❌ Not supported
macOS Desktop	❌ Not supported
Windows Desktop	❌ Not supported
Linux Desktop	❌ Not supported

Native SDK Dependencies

The following packages are included automatically as transitive dependencies. You do not need to add them manually to your app.

Platform	Dependency	Version	Source
Android	`com.github.plural-pinelabs:Pinelabs-Android-SDK`	1.10.0	JitPack
iOS	`PineLabsOnline_IOS_SDK.xcframework`	Bundled	Vendored in plugin

2. Integrate APIs in Your Backend

Start a payment by triggering the payment flow. To start a payment follow the below steps:

2.1. Generate Auth Token

Integrate our Generate Token API in your backend servers to generate the auth token. Use the token generated to authenticate Pine Labs Online APIs.

Below are the sample requests and response for the Generate Token API.

cURL

curl --location 'https://pluraluat.v2.pinepg.in/api/auth/v1/token' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--data '
{
  "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232",
  "client_secret": "fgwei7egyhuggwp39w8rh",
  "grant_type": "client_credentials"
}
'

Refer to our Generate Token API documentation to learn more.

2.2. Generate Checkout Link

Use this API to Generate a checkout link, for authentication use the generated access token in the headers of the API request.

Below are the sample requests and response for a Generate Checkout Link API.

cURL

curl --location 'https://pluraluat.v2.pinepg.in/api/checkout/v1/orders' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
  "merchant_order_reference": "f4c45dbd-6eba-453d-b317-158c6ba12825",
  "order_amount": {
    "value": 500,
    "currency": "INR"
  },
  "purchase_details": {
    "customer": {
      "email_id": "joe.sam@gmail.com",
      "first_name": "joe",
      "last_name": "kumar",
      "customer_id": "192212",
      "mobile_number": "192192883",
      "country_code": "91",
      "billing_address": {
        "address1": "H.No 15, Sector 17",
        "address2": "",
        "address3": "",
        "pincode": "61232112",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      },
      "shipping_address": {
        "address1": "H.No 15, Sector 17",
        "address2": "",
        "address3": "",
        "pincode": "144001123",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      }
    },
    "merchant_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "integration_mode": "SDK"
  }
}
'

Refer to our Generate Checkout Link documentation to learn more.

3. SDK Installation & Initialization

Installation

To integrate the Pine Labs Online React Native Mobile SDK, first install the SDK package and complete the required platform-specific configuration. Install the latest version of the SDK using npm or Yarn.

Npm

npm install pinelabs-react-native-sdk

📘 Note:

During development, the SDK may be consumed using a local file dependency. For production integrations, always install the SDK from the published npm package.

Install iOS Dependencies

After installing the SDK, install the CocoaPods dependencies for the iOS project.

Code

cd ios
pod install
cd ..

React Native automatically links the native Android and iOS modules through the autolinking mechanism. No additional linking steps are required.

Configure Android

Complete the following Android-specific configuration before integrating the SDK.

Set the Minimum SDK Version

The SDK requires Android API level 26 or later.

If your project defines the SDK version in the app-level Gradle file, update the minSdkVersion as shown below.

Code

android {
    defaultConfig {
        minSdkVersion 26
    }
}

If your project manages SDK versions in the root Gradle file, update the configuration as follows:

Code

buildscript {
    ext {
        minSdkVersion = 26
        compileSdkVersion = 34
        targetSdkVersion = 34
    }
}

Add JitPack Repository

The Android SDK dependencies are distributed through JitPack.

For projects using settings.gradle, add the JitPack repository under dependencyResolutionManagement.

Code

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)

    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

For older Android projects using allprojects, update the root build.gradle file.

Code

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Enable Internet Permission

Verify that the following permission is declared in your application's AndroidManifest.xml file.

XML

<uses-permission android:name="android.permission.INTERNET" />

📘 Note:

The native Android SDK handles UPI intent schemes and payment app queries internally.

Configure the Application Theme

Use a visible AppCompat or Material theme to ensure that the SDK's payment screens are rendered correctly.

Code

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar" />

📘 Note:

If your application uses a custom theme, ensure that the text and background colours provide sufficient contrast so that payment input fields remain clearly visible.

iOS Configuration

Complete the following iOS-specific configuration before integrating the SDK.

Set the iOS Deployment Target

The SDK supports iOS 13.0 and later. Update the deployment target in your Podfile.

Code

platform :ios, '13.0'

After updating the deployment target, install the CocoaPods dependencies.

Code

cd ios
pod install
cd ..

Verify the SDK Framework

The required iOS framework is bundled with the npm package and is automatically integrated during installation.

Framework location:

Code

node_modules/pinelabs-react-native-sdk/ios/Frameworks/PineLabsOnline_IOS_SDK.xcframework

No additional framework configuration is required.

Configure UPI Query Schemes

If your application supports UPI payments on iOS, add the supported UPI application schemes to your application's Info.plist.

Code

<key>LSApplicationQueriesSchemes</key> 
<array> 
  <string>bhim</string> 
  <string>cred</string> 
  <string>credpay</string> 
  <string>tez</string> 
  <string>paytmmp</string> 
  <string>phonepe</string> 
  <string>kiwi</string> 
  <string>mobikwik</string> 
</array>

📘 Note:

The Pine Labs iOS SDK manages UPI application routing internally. These query schemes allow iOS to detect installed UPI applications before initiating the payment flow.

Start a Payment

Import the SDK and call startPayment with the order token received from your backend.

Your backend creates an order using the Generate Checkout Link API and receives a token in the response. Pass this token directly to the SDK.

Code

import React, { useState } from 'react';
import { Alert, Button, TextInput, View } from 'react-native';
import { startPayment } from 'pinelabs-react-native-sdk';

export function CheckoutScreen() {
  const [orderToken, setOrderToken] = useState('');
  const [isProcessing, setIsProcessing] = useState(false);

  const onPayNow = async () => {
    const token = orderToken.trim();

    if (!token) {
      Alert.alert('Payment Error', 'Order token is required');
      return;
    }

    try {
      setIsProcessing(true);
      const result = await startPayment(token, 'uat');

      switch (result.status) {
        case 'success':
          Alert.alert('Payment Successful', `Order ID: ${result.orderId}`);
          break;
        case 'failure':
          Alert.alert('Payment Failed', result.message || 'Payment failed');
          break;
        case 'cancelled':
          Alert.alert('Payment Cancelled', result.message || 'Payment was cancelled');
          break;
        case 'backPressed':
          Alert.alert('Payment Closed', result.message || 'User closed the payment flow');
          break;
      }
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unexpected error';
      Alert.alert('Payment Error', message);
    } finally {
      setIsProcessing(false);
    }
  };

  return (
    <View>
      <TextInput
        value={orderToken}
        onChangeText={setOrderToken}
        placeholder="Order token"
        autoCapitalize="none"
        autoCorrect={false}
      />
      <Button title={isProcessing ? 'Processing...' : 'Pay Now'} onPress={onPayNow} disabled={isProcessing} />
    </View>
  );
}

Parameters

Parameter	Type	Required	Description
`orderToken`	`String`	Yes	The token returned in the response of our Generate Checkout Link API. This token authenticates and identifies the payment session.
`environment`	`uat-prod`	No	The SDK environment. Use `uat` for testing and `prod` for production.

4. Handle Payments

You need to implement call-back methods to handle your payment responses. This will provide the payment status and reason for transaction failures. Based on the reasons for failures, handling can be built at your end. Transaction callbacks can be listened to via overriding methods of EdgeResponseCallback.

PaymentResult

Both SDK payment methods return a PaymentResult object when the payment flow ends.

Code

type PineLabsSuccessResponse = {
  type: 'success';
  status: 'success';
  orderId: string;
  message?: string;
  description?: string;
};

Payment Status

The SDK returns one of the following standard status values:

Status	Value	Description
`success`	`success`	Payment completed successfully. The order ID is available in `result.orderId`.
`failure`	`failure`	Payment failed due to bank decline, timeout, or other error. Check `result.message` for details.
`cancelled`	`cancelled`	User cancelled the payment from within the native payment UI.
`backPressed`	`backPressed`	User pressed the system back button (Android) or swipe-to-dismiss (iOS) to exit the payment screen.

5. Manage Transactions

Track and verify transaction status using Pine Labs APIs. To retrieve the latest status, use the Fetch APIs or subscribe to webhooks for real-time transaction updates.

Get Order by Order ID

Fetch real-time transaction status by order ID.

Learn More →

Webhooks

Configure webhook events for automatic transaction updates.

Learn More →