Integration Steps

Follow the below steps to integrate with Pine Labs Online payment gateway using iFrame setup.

📘
Note

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. [Prerequisite] Generate Token

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

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

curl --request POST \
--url 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 --request POST \
--url 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.

Dynamic Tabs

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 Plural 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 Plural 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. Create Checkout Link

Use this API to generate a checkout Link. Include the access token in the request headers for Bearer Authentication.

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

curl --request POST \
--url https://pluraluat.v2.pinepg.in/api/checkout/v1/orders \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--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":112345171,
  "order_amount":{
    "value":500,
    "currency":"INR"
  },
  "integration_mode":"IFRAME",
  "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":"192212",
      "mobile_number":"9876543210",
			"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":"DD",
      "key2":"XOF"
    }
  }
}
'

curl --request POST \
--url https://api.pluralpay.in/api/checkout/v1/orders \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--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":112345171,
  "order_amount":{
    "value":500,
    "currency":"INR"
  },
  "integration_mode":"IFRAME",
  "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":"192212",
      "mobile_number":"9876543210",
			"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":"DD",
      "key2":"XOF"
    }
  }
}
'

{
  "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."
}

Click here for request and response parameter information.

Dynamic Tabs

Request Parameters

Response Parameters

The table below lists the request parameters of our Create Checkout Link API.

Parameter	Type	Description
merchant_order_reference required	`string`	Enter a unique identifier for the order request. Minimum: 1 character. Maximum: 50 characters. Example: `1234567890` Supported characters: `A-Z` `a-z` `0-9` `-` `_`
order_amount required	`object`	An object that contains the transaction amount details. Learn more about the `order_amount` child object.
integration_mode	`string`	It is a payment processing approach that defines how transactions are handled. Example: `IFRAME`
pre_auth	`boolean`	The pre-authorization type. Possible values: `false` (default): When pre-authorization is not required. `true`: When pre-authorization is needed.
allowed_payment_methods	`array of strings`	The type of payment methods you want to offer customers. Accepted values: `CARD` `UPI` `POINTS` `NETBANKING` `WALLET` `CREDIT_EMI` `DEBIT_EMI` Example: CARD Note: Ensure it is configured for you.
notes	`string`	Note to show against an order. Example: `Order1`
purchase_details	`object`	An object that contains purchase details. Learn more about the `purchase_details` child object.

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the Create Checkout Link request object.

Parameter	Type	Description
value required	`integer`	Transaction amount in Paisa. Minimum value: `100` (₹1). Maximum value: `100000000` (₹10 lakh). Example: `1000`
currency required	`string`	Type of currency. Example: `INR`

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the Create Checkout Link request object.

Parameter	Type	Description
bank_details required	`object`	An object that contains the bank account details. Learn more about the `bank_details` child object.
customer	`object`	An object that contains the customer details. Learn more about the `customer` child object.
merchant_metadata	`object`	An object of key-value pair that can be used to store additional information. Example: `"key1": "DD"`

Bank Details [Child Object]

The table below lists the various parameters in the bank_details child object. This is part of the purchase_details object.

Parameter	Type	Description
account_number required	`string`	Customer's bank account number. Example: `500000004545`
ifsc_code	`string`	Customer's bank IFSC. Example: `BANK0000123`
bank_name	`string`	Customer's account holding bank name. Example: `Example Bank`

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter	Type	Description
email_id	`string`	Customer's email address. Minimum length: `1` character. Maximum length: `50` characters. Example: `[email protected]`
first_name	`string`	Customer's first name. Minimum length: `1` character. Maximum length: `50` characters. Example: `Kevin`
last_name	`string`	Customer's last name. Minimum length: `1` character. Maximum length: `50` characters. Example: `Bob`
customer_id	`string`	Unique identifier of the customer in the Plural database. Minimum length: `1` character. Maximum length: `19` characters. Example: `123456`
mobile_number	`string`	Customer's mobile number. Minimum length: `9` characters. Maximum length: `20` characters. Example: `9876543210`
billing_address	`object`	An object that contains the details of the billing address. Learn more about our `billing_address` child object.
shipping_address	`object`	An object that contains the shipping address details. Learn more about our `shipping_address` child object.

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter	Type	Description
address1	`string`	Customer's billing address1. Max length: `100` characters. Example: `10 Downing Street Westminster London`
address2	`string`	Customer's billing address2. Max length: `100` characters. Example: `Oxford Street Westminster London`
address3	`string`	Customer's billing address3. Max length: `100` characters. Example: `Baker Street Westminster London`
pincode	`string`	Pincode of the billing address. Min length: `6` characters. Max length: `10` characters. Example: `51524036`
city	`string`	City of the billing address. Max length: `50` characters. Example: `Westminster`
state	`string`	State of the billing address. Max length: `50 characters.` `Example: Westminster`
country	`string`	Country of the billing address. Max length: `50` characters. Example: `London`

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter	Type	Description
address1	`string`	Customer's shipping address1. Max length: `100` characters. Example: `10 Downing Street Westminster London`
address2	`string`	Customer's shipping address2. Max length: `100` characters. Example: `Oxford Street Westminster London`
address3	`string`	Customer's shipping address3. Max length: `100` characters. Example: `Baker Street Westminster London`
pincode	`string`	Pincode of the shipping address. Min length: `6` characters Max length: `10` characters. Example: `51524036`
city	`string`	City of the shipping address. Max length: `50` characters. Example: `Westminster`
state	`string`	State of the shipping address. Max length: `50` characters. Example: `Westminster`
country	`string`	Country of the shipping address. Max length: `50` characters. Example: `London`

The table below lists the various parameters returned in the Generate Checkout Link response objects.

Parameter	Type	Description
token	`string`	Token generated by our system for Plural Hosted Checkout. Example: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c`
order_id	`string`	Unique identifier of the order in the Plural database. Example: `v1-5757575757-aa-hU1rUd`
redirect_url	`string`	The checkout link generated on our system. Example: `https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=<>`
response_code	`integer`	Response code of the request. Example: `200`
response_message	`string`	Corresponding message to the response code. Example: `Order Creation Successful`

❗️
Watch OUT
The parameter "integration_mode": "IFRAME" is mandatory to render the iframe checkout.

Refer to our Test Card Details documentation to learn more.

3. Integrate with Checkout on Client Side

To integrate with iFrame checkout on Client Side use the below code.

<html>
<button id="pay_button">Pay</button>
<script src="https://checkout-staging.pluralonline.com/v3/web-sdk-checkout.js"></script>
<script>
function handleCheckout(redirectUrl) {
  const options = {
    redirectUrl,
    successHandler: async function (response) {
      console.log(response);
    },
    failedHandler: async function (response) {
        console.log(response);
    },
  };

  const plural = new Plural(options);
  plural.open(options);
}

document.getElementById("pay_button").onclick = function(e){
    handleCheckout("https://api-staging.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_N7fMbGAfE8xDtTMLptiWhWL%2Fgz7bv0aBUuFRH5NlzAPYpii%2BcRyvm1xllb8TP5JG"); // Pass `redirect_url` returned in our Create Checkout API response.
}
</script>
</html>

<html>
<button id="pay_button">Pay</button>
<script src="https://checkout.pluralonline.com/v3/web-sdk-checkout.js"></script>
<script>
function handleCheckout(redirectUrl) {
  const options = {
    redirectUrl,
    successHandler: async function (response) {
      console.log(response);
    },
    failedHandler: async function (response) {
        console.log(response);
    },
  };

  const plural = new Plural(options);
  plural.open(options);
}

document.getElementById("pay_button").onclick = function(e){
    handleCheckout("https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_xyvekQA0C%2FvgX3fWU4iIM… // Pass `redirect_url` returned in our Create Checkout API response.
}
</script>
</html>

Configuration Object: To View Click Here

Defines a configuration object labeled as options that contains key settings listed below:

redirectUrl: Use this key to pass the redirect_url returned in our Create Checkout API response.
successHandler: Handler functions are asynchronous, where you can customize handlers according to your specific needs.
failureHandler: Handler functions are asynchronous, allowing you to add handlers to notify users as required based on specific requirements.

4. Handle Transaction Response

You can add custom handler logic to manage specific actions or events within the successHandlerand failureHandler function to enhance responsiveness. It is essential to handle both successHandler and failureHandler functions and signature verification.

4.1 Handle Payment Success and Failure

On a successful and failed payment we return the following parameters listed below.

{
  "order_id": "v1-4405071524-aa-qlAtAf",
  "status": "AUTHORIZED",
  "signature": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}

{
  "order_id": "v1-4405071524-aa-qlAtAf",
  "status": "FAILED",
  "signature": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}

We recommend you to collect the payment details and send them to your server.
You must validate the authenticity of the payment details returned. You can authenticate by verifying the signature.

4.2 Verify Payment Signature

Ensure you follow this as a mandatory step to verify the authenticity of the details returned to the checkout form for successful payments.

Follow the below steps to verify the signature.

Create a signature on your server using the following parameters using the SHA256 algorithm.
1. order_id: Unique Identifier generated for an order request on Pine Labs Online database.
2. status: Payment status.
3. secret_key: The Onboarding team has provided you with this information as part of the onboarding process.

Use the below sample code to construct HashMap signature using the SHA256 algorithm.

import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
 
public class hash {
    public static void main(String[] args) {
        // Test the GenerateHash method
        String input = "<string>";
        String secretKey = "<secret_key>";  // Example key in hex
 
        String hash = GenerateHash(input, secretKey);
        System.out.println("Generated Hash: " + hash);
    }
    public static String GenerateHash(String input, String strSecretKey) {
        String strHash = "";
        try {
            if (!isValidString(input) || !isValidString(strSecretKey)) {
                return strHash;
            }
            byte[] convertedHashKey = new byte[strSecretKey.length() / 2];
 
            for (int i = 0; i < strSecretKey.length() / 2; i++) {
                convertedHashKey[i] =
                        (byte)Integer.parseInt(strSecretKey.substring(i * 2, (i*2)+2),16); //hexNumber radix
            }
            strHash = hmacDigest(input.toString(), convertedHashKey,
                    "HmacSHA256");
        } catch (Exception ex) {
            strHash = "";
        }
        return strHash.toUpperCase();
    }
    private static String hmacDigest(String msg, byte[] keyString, String algo) {
        String digest = null;
        try {
            SecretKeySpec key = new SecretKeySpec(keyString, algo);
            Mac mac = Mac.getInstance(algo);
            mac.init(key);
            byte[] bytes = mac.doFinal(msg.getBytes("UTF-8"));
            StringBuffer hash = new StringBuffer();
            for (int i = 0; i < bytes.length; i++) {
                String hex = Integer.toHexString(0xFF & bytes[i]);
                if (hex.length() == 1) {
                    hash.append('0');
                }
                hash.append(hex);
            }
            digest = hash.toString();
        } catch (UnsupportedEncodingException e) {
// logger.error("Exception occured in hashing the pine payment gateway request"+e);
        } catch (InvalidKeyException e) {
// logger.error("Exception occured in hashing the pine payment gateway request"+e);
        } catch (NoSuchAlgorithmException e) {
// logger.error("Exception occured in hashing the pine payment gateway request"+e);
        }
        return digest;
    }
    public static boolean isValidString(String str){
        if(str != null && !"".equals(str.trim())){
            return true;
        }
        return false;
    }
}

📘
Note:
To create a request string, format the key-value pairs of data returned to the return URL. The pairs are separated by & and arranged in ascending order based on a lexicographical comparison of the keys.

Shown below is a example to create a request string.

"key1=value1&key2=value2", ["order_id=random_order_id&status=AUTHORIZED"]

"key1=value1&key2=value2&key3=value3&key4=value4", ["error_code=USER_AUTHENTICATION_FAILED&error_message=Consumer Authentication required&order_id=<order_id>&status=FAILED"]

If the signature generated on your server matches the Pine Labs Online signature returned, it confirms that the payment details are from Pine Labs Online.

To Know Your Payment Status

To check your payment status, you can either rely on Webhook events or use our Get Orders APIs for real-time updates.

Webhook Notification: We send Webhook notifications on the successful payment or any changes to the payments object. Refer to our Webhooks documentation to learn more.
Get Orders API: Use our Get Orders API to know the real time status of the payment. Refer to our Manage Orders documentation to learn more.

Refunds

Pine Labs Online processes refund directly to the customer's original payment method to prevent chargebacks.

Refer to our Refunds documentation to learn more.

Integration Steps

📘
Note

1. [Prerequisite] Generate Token

2. Create Checkout Link

Order Amount [Child Object]

Purchase Details [Child Object]

Bank Details [Child Object]

Customer [Child Object]

Billing Address [Child Object]

Shipping Address [Child Object]

❗️
Watch OUT

3. Integrate with Checkout on Client Side

4. Handle Transaction Response

4.1 Handle Payment Success and Failure

4.2 Verify Payment Signature

📘
Note:

To Know Your Payment Status

Refunds

📘Note

1. [Prerequisite] Generate Token

2. Create Checkout Link

Order Amount [Child Object]

Purchase Details [Child Object]

Bank Details [Child Object]

Customer [Child Object]

Billing Address [Child Object]

Shipping Address [Child Object]

❗️Watch OUT

3. Integrate with Checkout on Client Side

4. Handle Transaction Response

4.1 Handle Payment Success and Failure

4.2 Verify Payment Signature

📘Note:

To Know Your Payment Status

Refunds

📘
Note

❗️
Watch OUT

📘
Note: