Pine LabsDOCS
Create Account

Integration Steps

Integration Steps documentation.

View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in Perplexity

Follow the below steps to integrate with Pine Labs Online seamless checkout APIs to start accepting International payments on your application.

  1. [Prerequisite] Generate Token
  2. Create Order
  3. Create Payment
  4. Handle Payment
    1. Store Payment Details on Your Server
    2. Verify Payment Signature
  5. Get Order by Order ID

📘 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.

🚧 Watch Out

  • To Integrate with Pine Labs Online seamless checkout flow you must have a PCI compliance certificate.

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
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. Create Order

To create an Order, use our Create Order API, for authentication use the generated access token in the headers of the API request.

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

cURL
curl --location 'https://pluraluat.v2.pinepg.in/api/pay/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": "fc493db3-e497-48a3-8ad5-dea883b6a0a0",
  "order_amount": {
    "value": 10000,
    "currency": "USD"
  },
  "notes": null,
  "purchase_details": {
    "customer": {
      "email_id": "",
      "first_name": "John",
      "last_name": "Doe",
      "customer_id": 192212,
      "mobile_number": "",
      "country_code": 91,
      "billing_address": {
        "address1": "H.No 15, Sector 17",
        "address2": null,
        "address3": null,
        "pincode": 160036,
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA",
        "full_name": "vikas",
        "address_type": "HOME",
        "address_category": "BILLING"
      },
      "shipping_address": {
        "address1": "H.No 15, Sector 17",
        "address2": null,
        "address3": null,
        "pincode": 160036,
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA",
        "full_name": "vikas",
        "address_type": "HOME",
        "address_category": "SHIPPING"
      },
      "merchant_customer_reference": null,
      "is_edit_customer_details_allowed": false,
      "status": null,
      "gstin": null,
      "merchant_metadata": {
        "customerCreationDate": "2025-06-20",
        "customerCreationDays": "10",
        "customerType": "NEW"
      },
      "status_reason": null,
      "failure_reason": null,
      "created_at": null,
      "updated_at": null
    },
    "merchant_metadata": {
      "customerCreationDate": "2025-06-20",
      "customerCreationDays": "10",
      "customerType": "NEW"
    },
    "merchant_metadata_object": null,
    "account_details": null,
    "products": null,
    "split_info": null,
    "cart_coupon_discount_amount": null
  },
  "allowed_payment_methods": null,
  "integration_mode": null,
  "callback_url": null,
  "is_v2_transaction": null,
  "plugin_data": null,
  "failure_callback_url": null,
  "v2_payment_id": null,
  "payment_link_id": null,
  "part_payment": true,
  "is_mcc_transaction": true,
  "base_amount": {
    "value": 1000,
    "currency": "INR"
  }
}
'

Refer to our Create Order API documentation to learn more.

3. Create Payment

To create a payment, use our Create Payment API, use the order_id returned in the response of a Create Order API to link the payment against an order.

Below are the sample requests and sample response for Card Payment API.

cURL
curl --location 'https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{order_id}/payments' \
--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 '
{
  "payments": [
    {
      "merchant_payment_reference": "test-prn-15-07-25-86",
      "payment_method": "CARD",
      "payment_amount": {
        "value": 10000,
        "currency": "USD"
      },
      "payment_option": {
        "card_details": {
          "name": "INDRANI DUTTA",
          "card_number": "4622943127013713",
          "cvv": "123",
          "expiry_month": "01",
          "expiry_year": "2026"
        }
      },
      "risk_validation_details": {
        "email_id": "test@gmail.com",
        "first_name": "John",
        "last_name": "Doe",
        "customer_id": "192212",
        "mobile_number": "8851310053",
        "country_code": "91",
        "billing_address": {
          "address1": "H.No 15, Sector 17",
          "address2": null,
          "address3": null,
          "pincode": "160036",
          "city": "CHANDIGARH",
          "state": "PUNJAB",
          "country": "INDIA",
          "full_name": "vikas",
          "address_type": "HOME",
          "address_category": "BILLING"
        }
      },
      "device_info": {
        "device_type": "DEVICE_TYPE_WEB",
        "source_ip": "69.48.236.73",
        "browser_user_agent": "Chrome",
        "browser_accept_header": "*/*",
        "browser_language": "en-US",
        "browser_screen_height": "900",
        "browser_screen_width": "1440",
        "browser_window_size": "1440x686",
        "browser_timezone": "-330",
        "browser_ipaddress": "69.48.236.73",
        "browser_screen_color_depth": "30",
        "browser_java_enabled_val": "true",
        "browser_javascript_enabled_val": "true",
        "device_channel": "1757592476801gSc3aeIiCO"
      },
      "base_amount": {
        "value": 1000,
        "currency": "INR"
      }
    }
  ]
}
'

Refer to our Create Payment API documentation to learn more.

4. Handle Payment

In create payment API response we return a challenge_url, use this challenge url to navigate your customers to the checkout page to accept payment.

4.1 Store Payment Details on Your Server

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

  • 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.
JSON
{
  "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 Online 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.

Java
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.

Text
"key1=value1&key2=value2", ["order_id=random_order_id&status=PROCESSED"]
  1. If the signature generated on your server matches the Pine Labs Online signature returned in the return URL, it confirms that the payment details are from Pine Labs Online.

5. Get Order by Order ID

Use this API to retrieve the order by order ID.

Use the below endpoint to capture the payment against the order.

Text
GET: https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{order_id}

Shown below is a sample request and sample response for a Get Order by Order ID API.

JSON
{
  "data":{
    "order_id":"v1-250124055307-aa-6OZ8sm",
    "merchant_order_reference":"53cf1451-4dfd-417d-a1c8-c8bd603d5200",
    "type":"CHARGE",
    "status":"PENDING",
    "challenge_url":"https://pluraluat.v2.pinepg.in/web/auth/landing/?token=S50f2FXi%2FYAGe2bLZEW%2FA2VHzXthz0m9igmtsP61ODtY5u4pR6RYB5IlJwK0%2Fuo%2FBs9",
    "merchant_id":"111163",
    "order_amount":{
      "value":10000,
      "currency":"USD"
    },
    "pre_auth":false,
    "callback_url":"https://sample-callback-url",
    "failure_callback_url": "https://sample-failure-callback-url",
    "allowed_payment_methods":[
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],
    "purchase_details":{
      "customer":{
        "country_code":"91",
        "billing_address":{
          
        },
        "shipping_address":{
          
        },
        "is_edit_customer_details_allowed":false
      }
    },
    "payments":[
      {
        "id":"v1-250124055307-aa-6OZ8sm-ce-a",
        "merchant_payment_reference":"c7a7f778-b68f-462b-a6af-50698df12a4a",
        "status":"FAILED",
        "payment_amount":{
          "value":1550000,
          "currency":"INR"
        },
        "payment_method":"CREDIT_EMI",
        "offer_data":{
          "offer_details":{
            "id":"6",
            "name":"HDFC CC",
            "issuer_type":"CC_BANK",
            "priority":1,
            "tenure":{
              "tenure_id":"1",
              "name":"3 Months",
              "tenure_type":"MONTH",
              "tenure_value":3,
              "issuer_offer_parameters":[
                {
                  "program_type":"BANK_EMI",
                  "offer_id":"1803",
                  "offer_parameter_id":"72559"
                },
                {
                  "program_type":"MERCHANT_BANK_OFFER",
                  "offer_id":"1523",
                  "offer_parameter_id":"63566"
                }
              ],
              "details":[
                
              ],
              "discount":{
                "discount_type":"INSTANT",
                "amount":{
                  "currency":"INR",
                  "value":50000
                },
                "breakup":{
                  "merchant":{
                    
                  },
                  "issuer":{
                    
                  },
                  "brand":{
                    
                  },
                  "dealer":{
                    
                  }
                }
              },
              "auth_amount":{
                "currency":"INR",
                "value":1550000
              },
              "loan_amount":{
                "currency":"INR",
                "value":1550000
              },
              "total_discount_amount":{
                "currency":"INR",
                "value":50000
              },
              "net_payment_amount":{
                "currency":"INR",
                "value":1601952
              },
              "monthly_emi_amount":{
                "currency":"INR",
                "value":533984
              },
              "total_emi_amount":{
                "currency":"INR",
                "value":1601952
              },
              "interest_amount":{
                "currency":"INR",
                "value":51952
              },
              "interest_rate_percentage":20,
              "processing_fee_details":{
                "amount":{
                  "currency":"INR",
                  "value":19900
                }
              },
              "processing_fee_amount":{
                "currency":"INR",
                "value":19900
              },
              "emi_type":"STANDARD"
            }
          }
        },
        "error_detail":{
          "code":"INTERNAL_ERROR",
          "message":"Payment processor is unavailable"
        },
        "created_at":"2025-01-24T05:53:24.476Z",
        "updated_at":"2025-01-24T05:53:25.492Z"
      },
      {
        "id":"v1-250124055307-aa-6OZ8sm-ce-b",
        "merchant_payment_reference":"32e3ba62-bb95-41bb-be81-1b87ab96c0ed",
        "status":"PENDING",
        "payment_amount":{
          "value":1550000,
          "currency":"INR"
        },
        "payment_method":"CREDIT_EMI",
        "payment_option":{
          "card_data":{
            "card_type":"CREDIT",
            "network_name":"VISA",
            "issuer_name":"INTL HDQTRS-CENTER OWNED",
            "card_category":"Consumer",
            "country_code":"IND",
            "token_txn_type":"ALT_TOKEN",
            "save":false
          }
        },
        "acquirer_data":{
          "approval_code":"",
          "acquirer_reference":"",
          "rrn":"",
          "is_aggregator":true
        },
        "offer_data":{
          "offer_details":{
            "id":"6",
            "name":"HDFC CC",
            "issuer_type":"CC_BANK",
            "priority":1,
            "tenure":{
              "tenure_id":"1",
              "name":"3 Months",
              "tenure_type":"MONTH",
              "tenure_value":3,
              "issuer_offer_parameters":[
                {
                  "program_type":"BANK_EMI",
                  "offer_id":"1803",
                  "offer_parameter_id":"72559"
                },
                {
                  "program_type":"MERCHANT_BANK_OFFER",
                  "offer_id":"1523",
                  "offer_parameter_id":"63566"
                }
              ],
              "details":[
                
              ],
              "discount":{
                "discount_type":"INSTANT",
                "amount":{
                  "currency":"INR",
                  "value":50000
                },
                "breakup":{
                  "merchant":{
                    
                  },
                  "issuer":{
                    
                  },
                  "brand":{
                    
                  },
                  "dealer":{
                    
                  }
                }
              },
              "auth_amount":{
                "currency":"INR",
                "value":1550000
              },
              "loan_amount":{
                "currency":"INR",
                "value":1550000
              },
              "total_discount_amount":{
                "currency":"INR",
                "value":50000
              },
              "net_payment_amount":{
                "currency":"INR",
                "value":1601952
              },
              "monthly_emi_amount":{
                "currency":"INR",
                "value":533984
              },
              "total_emi_amount":{
                "currency":"INR",
                "value":1601952
              },
              "interest_amount":{
                "currency":"INR",
                "value":51952
              },
              "interest_rate_percentage":20,
              "processing_fee_details":{
                "amount":{
                  "currency":"INR",
                  "value":19900
                }
              },
              "processing_fee_amount":{
                "currency":"INR",
                "value":19900
              },
              "emi_type":"STANDARD"
            }
          }
        },
        "created_at":"2025-01-24T05:53:58.092Z",
        "updated_at":"2025-01-24T05:53:59.679Z"
      }
    ],
    "created_at":"2025-01-24T05:53:07.740Z",
    "updated_at":"2025-01-24T05:53:59.680Z",
    "integration_mode":"SEAMLESS",
    "payment_retries_remaining":8
  }
}

Refer to our Get Order by Order ID API documentation to learn more.

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.

  1. 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.
  2. 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.
  3. 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.
PreviousMulti Currency Conversion (MCC)NextSupported Currencies
New chat
Responses are generated using AI and may contain mistakes.
Hi! I'm Pine, your AI developer assistant. Ask me anything about Pine Labs APIs, integrations, or troubleshooting.

Tip: you can create a new chat with ⌘ + E
MCC Integration Steps — Multi-Currency Payment Flow | Pine Labs