Integration Steps

Follow the below steps to integrate with Pine Labs Hosted checkout APIs in your application.

1. [Prerequisite] Generate Token
2. Generate Checkout Link
3. Launch Checkout
4. Handle Callback

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

Refer to our Generate Token API documentation to learn more.

2. Generate Checkout Link

To generate a Pine Labs Hosted checkout link, use our Generate Checkout Link API. Include the access token in the request headers for Bearer Authentication.

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 '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": "112345",
  "order_amount": {
    "value": 1100,
    "currency": "INR"
  },
  "integration_mode": "REDIRECT",
  "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": "kevin.bob@example.com",
      "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": "Kevin Bob",
        "adddress_type": "Home",
        "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": "Kevin Bob",
        "adddress_type": "Home",
        "address_category": "shipping"
      }
    },
    "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"
        }
      ]
    }
  }
}
'

📘 Note:

• You can set pre-auth as true to use pre-authorization flow for card payments only through hosted checkout.

Refer to our Generate Checkout Link API documentation to learn more.

3. Launch Checkout

After successfully generating the checkout link, launch the checkout using the redirect_url. This can be done as listed below.

In the response to the Generate Checkout Link API, a redirect_url is returned. Use this URL to redirect your customers to the Pine Labs - Hosted checkout page to accept payment.

After successfully completing the payment to know the status of the payment we sent the response to the callback_url.

4. Handle Callback

On a successful and failed payment we return the following fields to the return url.

4.1. Store Payment Details on Your Server

• We recommend you to store the payment details on your server.
• You must validate the authenticity of the payment details returned. You can authenticate by verifying the signature.

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

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.

1. 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 database.
   2. payment_status: Payment status.
   3. error_code: Short code for the error returned.
   4. error_message: Corresponding error message for the code.
   5. 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=PROCESSED"]

2. If the signature generated on your server matches the Pine Labs signature returned in the return URL, it confirms that the payment details are from Pine Labs.
3. Capture the status returned on your database. Once the payment status is AUTHORIZED you can either capture or cancel an order.

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.

Pre Authorization Flow

Our Orders API includes an optional pre-authorization feature. When pre-authorization is enabled (pre_auth = true), you can Capture a Payment for an order after successful delivery, ensuring that settlement remains on hold until then.

📘 Note:

For pre_auth true

• On successful payment we send the webhook event ORDER_AUTHORIZED and the status of the payment is updated to AUTHORIZED.
• You can capture or cancel an order only when the order status is AUTHORIZED.

For pre_auth false

• On successful payment we send the webhook event ORDER_PROCESSED and the status of the payment is updated to PROCESSED

Once pre-authorization is enabled and the payment is successfully authorized, you have the following options:

Capture Order: Utilize the Pine Labs Online capture order API in your backend to capture the payment against an order.

Cancel Order: Use the Pine Labs Online cancel order API in your backend to cancel the payment against an order.

1. Capture Order

Use this API to capture the payment against an order. On successful capture of an order the order status is updated as processed.

Shown below are the sample requests and sample response for a Capture Order API.

curl --request PUT \
     --url https://pluraluat.v2.pinepg.in/api/pay/v1/orders/order_id/capture \
     --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_capture_reference": "merchant-capture-ref-r4y",
  "capture_amount": {
    "value": 4000,
    "currency": "INR"
  }
}
'

Refer to our Capture Order API documentation to learn more.

2. Cancel Order

Use this API to cancel the payment against an order.

Shown below are the sample requests and sample response for a Cancel Order API.

curl --request PUT \
  --url https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{order_id}/cancel \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --header 'Request-Timestamp: 2026-06-01T00:00:00.000Z'

Refer to our Cancel Order API documentation to learn more.