Web SDK Integration Steps – Pine Labs Payment Gateway

❗️
Security Best Practices:

Ensure you store your Client ID and 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

Android iOS React

Android Requirements:

Android SDK version 21 (Lollipop) or higher
Pine Labs Web SDK .aar file
Android Studio 4.0 or higher
Internet permissions configured in AndroidManifest.xml

iOS Requirements:

iOS 12.0 or higher
Xcode 12.0 or higher
Pine Labs Web SDK .xcframework file
Swift 5.0 or Objective-C support

React Requirements:

Node.js 14.0 or higher
React 16.8 or higher
npm or yarn package manager
Modern browser with ES6+ support

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 --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"
}
'

curl --location 'https://api.pluralpay.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"
}
'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 3600
}

Click here for request and response parameter information.

Request Parameters

Response Parameters

The table below lists the request parameters of our Generate Token API.

Parameter	Type	Description
client_id required	`string`	Unique client identifier in the Pine Labs Online database. Example: `a17ce30e-f88e-4f81-ada1-c3b4909ed232` Note: The Onboarding team has provided you with this information as part of the onboarding process.
client_secret required	`string`	Unique client secret key provided while onboarding. Example: `fgwei7egyhuggwp39w8rh` Note: The Onboarding team has provided you with this information as part of the onboarding process.
grant_type required	`string`	The grant type to generate an access token. Accepted value: `client_credentials`

The table below lists the response parameters of our Generate Token API.

Parameter	Type	Description
access_token	`string`	The access token generated by the system. • Minimum length: 1 character. • Maximum length: 8192 characters. Example: `eyJhbGciOiJIUzI1NiIsIn` Note: Use this token in the authorization headers to authenticate Pine Labs Online APIs.
expires_at	`string`	Access duration timestamp. Example: `2024-06-28T13:26:06.909140Z`

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 --request POST \
     --url https://pluraluat.v2.pinepg.in/api/checkout/v1/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "merchant_order_reference": "112345",
  "order_amount": {
    "value": 1100,
    "currency": "INR"
  },
  "integration_mode": "SDK",
  "pre_auth": false,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "notes": "order1",
  "callback_url": "https://sample-callback-url",
  "failure_callback_url": "https://sample-failure-callback-url",
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "Kevin",
      "last_name": "Bob",
      "customer_id": "123456",
      "mobile_number": "9876543210",
			"country_code": "91",
      "billing_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      },
      "shipping_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      }
    },
    "merchant_metadata": {
      "express_checkout_enabled": "TRUE",
      "express_checkout_allowed_action": "checkoutCollectAddress",
      "key1": "DD",
      "key2": "XOF"
    }
  },
  "cart_details": {
    "cart_items": [
      {
        "item_id": "cart_id_1",
        "item_name": "T Shirt",
        "item_description": "Test Description",
        "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_original_unit_price": 1,
        "item_discounted_unit_price": 1,
        "item_quantity": 1,
        "item_currency": "INR"
      }
    ]
  }
}
'

curl --request POST \
     --url https://api.pluralpay.in/api/checkout/v1/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "merchant_order_reference": "112345",
  "order_amount": {
    "value": 1100,
    "currency": "INR"
  },
  "integration_mode": "SDK",
  "pre_auth": false,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "notes": "order1",
  "callback_url": "https://sample-callback-url",
  "failure_callback_url": "https://sample-failure-callback-url",
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "Kevin",
      "last_name": "Bob",
      "customer_id": "123456",
      "mobile_number": "9876543210",
			"country_code": "91",
      "billing_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      },
      "shipping_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      }
    },
    "merchant_metadata": {
      "express_checkout_enabled": "TRUE",
      "express_checkout_allowed_action": "checkoutCollectAddress",
      "key1": "DD",
      "key2": "XOF"
    }
  },
  "cart_details": {
    "cart_items": [
      {
        "item_id": "cart_id_1",
        "item_name": "T Shirt",
        "item_description": "Test Description",
        "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_original_unit_price": 1,
        "item_discounted_unit_price": 1,
        "item_quantity": 1,
        "item_currency": "INR"
      }
    ]
  }
}
'

{
  "token": "REDIRECT TOKEN",
  "order_id": "ORDER ID",
  "redirect_url": "https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=REDIRECT TOKEN",
  "response_code": 200,
  "response_message": "Order Creation Successful."
}

Refer to our Generate Checkout Link documentation to learn more.

3. SDK Installation & Initialization

Android iOS React

3.1. Installation

Step 1: Add SDK to Project

To add the SDK to your app, import the .aar file to the project using the following steps:

From the Android Studio package manager, select project.
Create a new directory in a project named libs.
Download your Android SDK .aar file here.
Paste your .aar file inside the libs folder.

Step 2: Configure build.gradle

Include the below dependencies in your build.gradle file.


                                    implementation files('libs/EDGE-SDK.aar')

After adding the necessary dependencies to your build.gradle file, sync your project.

Step 3: Add Permissions

Include the following code in your AndroidManifest.xml file to obtain the required static permissions.


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

Note: The minimum supported Android version is Android 10 or higher.

3.2. Initialization

To initialise the android web SDK, follow the below steps:

Create an EdgeManager object: Initialise an instance of EdgeManager as shown below in your project.

 val edgeManager = EdgeManager()

Invoke startPayment: Use the edgeManager object to call the startPayment method, which is defined in the Android SDK.

 edgeManager.startPayment(context, redirectUrl, EdgeResponseCallback)

3.1. Installation

To add the SDK to your app, import the PineLabsWebSDK.xcframework file to the project using the following steps:

Step 1: Download the SDK Framework

You can download the SDK as a .xcframework file here, which is in a package format that Apple recommends for distributing binary frameworks.

Step 2: Add Framework to Your Package

Drag and Drop: Drag and drop the PineLabsWebSDK.xcframework file into your Xcode project in the Project Navigator under the Frameworks section.
Select Target: A dialog box will appear when you drop the PineLabsWebSDK.xcframework file into your project. Ensure that the checkbox labeled Copy items if needed is selected.

This ensures that the framework gets copied into your project directory, making it available whenever you need to build the project.

Watch Out: Ensure that the minimum compilation compatibility version is set to iOS 16 or 17.

Step 3: Configure the App Target

Follow the steps below to configure the target and ensure proper embedding of the SDK framework.

Open your target’s General tab in Xcode.
In the Frameworks, Libraries, and Embedded Content section, add the PineLabsWebSDK.xcframework file.
Select Embed & Sign for the added framework.

This ensures the framework is embedded in your app and properly signed when the app is built, enabling it to run on iOS devices.

Note: Once the PineLabsWebSDK.xcframework is embedded, you can import the package in the view controller.

Step 4: Network Check

The SDK uses a network connectivity function to access a URL (example.com). To enable this functionality, update your app’s Info.plist (Information Property List) file to permit the connection.

Ensure: Once this is added, you can check if the exception is being displayed in the Signing and Capabilities tab.

3.2. Initialization

To initialise the iOS web SDK, follow the below steps:

Import the SDK into the app.
Create an object of the class EdgeController to start a payment function.

You are creating a function in your app that passes the redirect [challenge] URL to start the payment function of our SDK.

 import UIKit
import IOS_SDK_V2

class ViewController: UIViewController {

    func UsingFramework(redirectUrl: String) {
        let IOS_Framework_Object = EdgeController()
        IOS_Framework_Object.startPayment(from: self, withURL: redirectUrl, callBack: ResponseCallback())
    }
}

3.1. Installation

Add Plugin Dependency:

Open your terminal or command prompt.
Run the following command to install the React Plugin.

 add react-native-webview

Note:

You can use the npm equivalent command to install react-native-webview.

3.2. Initialization

To Initialize the React Web SDK create startPayment_ inside your App.tsx

import { NewAppScreen } from '@react-native/new-app-screen';
import { StatusBar, StyleSheet, useColorScheme, View } from 'react-native';
import {
  SafeAreaProvider,
  useSafeAreaInsets,
} from 'react-native-safe-area-context';
import SimpleWebView from 'react-native-plural';
import { SafeAreaView, Alert } from 'react-native';

function App() {
  const isDarkMode = useColorScheme() === 'dark';

  return (
    <SafeAreaProvider>
      <StatusBar barStyle={isDarkMode ? 'light-content' : 'dark-content'} />
      <AppContent />
    </SafeAreaProvider>
  );
}

function AppContent() {
  console.log('App mounted LOG FROM EXAMPLE APP');
  const safeAreaInsets = useSafeAreaInsets();

  const handlePaymentResult = (res: {
    status: 'response' | 'error';
    url?: string;
    reason?: string;
  }) => {
    console.log('onPaymentResult called with:', res);
    if (res.status === 'response' || res.status === 'error') {
      Alert.alert('Payment from App: ' + res.url, res.reason);
      // Once the callback is received, merchant should call the Enquiry API
      // and based on the transaction status, navigate to success/failure screen
    }
  };

  return (
    <>
      <StatusBar barStyle="dark-content" backgroundColor="#fff" />
      <SafeAreaView style={{ flex: 1 }}>
        <SimpleWebView
          source={{ uri: 'https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_A%2BOTFc%2Fn%2BqnxE%2BJgOhg9Z8BxbA7izZXBGxviC%2FcxJFFhpIncIzNudxaf9FD9iEXX' }}
          style={{ flex: 1 }}
          onPaymentResult={handlePaymentResult}
          stopNavigationOnMatch={true}
        />
      </SafeAreaView>
    </>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

export default App;

Note:

Integrate the Create Order API first, and provide the redirect_url to the SDK.
After the SDK invokes the onPaymentResult callback with the payment response, call the Get Order by Order ID API to fetch the final transaction status.

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.

Payment Callbacks Section

onTransactionResponse

This method is called when the transaction is completed. Transaction can be a failure or a success.

internetNotAvailable

This method is called when the internet is not available.

onErrorOccured

This method is called when SDK is unable to load the payment page.

onPressedBackButton

This method is called when the user presses the back button.

onCancelTxn

This method is called when the user cancels the transaction.

4.1. Implementation Code Samples

override fun onInternetNotAvailable(code: Int, message: String?) {
    Toast.makeText(context: this, message, Toast.LENGTH_SHORT).show()
}

override fun onErrorOccurred(code: Int, message: String?) {
    Toast.makeText(context: this, text: "Error occurred ->$message", Toast.LENGTH_SHORT).show()
}

override fun onTransactionResponse() {
    Toast.makeText(context: this, text: "Transaction success", Toast.LENGTH_SHORT).show()
    inquiryDetails(token)
}

override fun onCancelTxn(code: Int, message: String?) {
    Toast.makeText(context: this, message, Toast.LENGTH_SHORT).show()
}

override fun onPressedBackButton(code: Int, message: String?) {
    Toast.makeText(context: this, message, Toast.LENGTH_SHORT).show()
}

public class MerchantCallbackResponse: UIViewController, ResponseCallback {
    
    public func internetNotAvailable(code: Int, message: String) {
        print("Test app response: internet not available")
    }

    public func onErrorOccured(code: Int, message: String) {
        print("Test app response: error occurred")
    }

    public func onTransactionResponse() {
        print("Test app response: transaction response")
    }

    public func onCancelTxn(code: Int, message: String) {
        print("Test app response: transaction cancelled")
    }

    public func onPressedBackButton(code: Int, message: String) {
        print("Test app response: back pressed")
    }
}

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

View API Documentation

Webhooks

Configure webhook events for automatic transaction updates

View Webhook Documentation

❗️Security Best Practices:

1. Prerequisites

Android Requirements:

iOS Requirements:

React Requirements:

2. Integrate APIs in Your Backend

3. SDK Installation & Initialization

4. Handle Payments

4.1. Implementation Code Samples

5. Manage Transactions

Get Order by Order ID

Webhooks

❗️
Security Best Practices: