Integration Flow
Learn how you can integrate with Plural APIs to start accepting payments on Plural hosted checkout.
The figure below shows the steps you need to follow to integrate with Plural hosted checkout APIs in your application.

Figure: Plural Hosted Checkout Integration Flow
1. Prerequisite
- Enter Payment Details: Use the below JSON to enter the payment Details. You are required to enter the
merchant_data
andpayment_data
child object.
{
"merchant_data": {
"merchant_id": 12345678,
"merchant_access_code": "4a8c422e-928d-4f84-bfe8-27a09af66647",
"unique_merchant_txn_id": "XYZ123",
"merchant_return_url": "https://www.pinelabs.com"
},
"payment_data": {
"amount_in_paisa": 800
},
"txn_data": {
"navigation_mode": "2",
"payment_mode": "1,3,4,19,10,11,14",
"transaction_type": "1",
"time_stamp": 157588000000
},
"customer_data": {
"email_id": "[email protected]",
"first_name": "Kevin",
"last_name": "Bob",
"customer_id": "123456",
"mobile_no": "9876543210",
"billing_data": {
"address1": "Chruch street",
"address2": "Brigade road",
"address3": "",
"pincode": "560018",
"city": "Bangalore",
"state": "Karnataka",
"country": "India"
},
"shipping_data": {
"address1": "Chruch street",
"address2": "Brigade road",
"address3": "",
"pincode": "560018",
"city": "Bangalore",
"state": "Karnataka",
"country": "India"
}
},
"udf_data": {
"udf_field_1": "Eecltronic purchase order",
"udf_field_2": "",
"udf_field_3": "",
"udf_field_4": ""
},
"product_details": [
{
"product_code": "7803",
"product_amount": "1000"
}
]
}
JSON Parameters
Click Here
The table below lists the various JSON parameters.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
merchant_data | object | M | An object that contains the merchant details. Learn more about our merchant_data child object. |
payment_data | object | M | An object that contains the payment details. Learn more about our payment_data child object. |
txn_data | object | M | An object that contains the transaction details. Learn more about our txn_data child object. |
customer_data | object | O | An object that contains the customer details. Learn more about our customer_data child object. |
udf_data | object | O | An object that contains the user defined details. Learn more about our udf_data child object. |
product_details | array of object | O | An object that contains the array of product details. Learn more about our product_details child object. |
Merchant Data [Child Object]
The table below lists the various parameters in the merchant_data
child object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
merchant_id | integer | M | Unique identifier of the merchant in the Plural database. Example: 123456 |
merchant_access_code | string | M | Unique merchant access code provided by Plural. Example: 4a8c422e-928d-4f84-bfe8-27a09af66647 |
unique_merchant_txn_id | string | M | Unique identifier of the specific transaction. Example: xyz123 |
merchant_return_url | string | M | Merchant return URL. Example: https://www.pinelabs.com Note: Your customer's are redirected to this page after the successful payment. |
Note:
- Contact our support team to know your
merchant_id
andmerchant_access_code
. Additionally you are required to whitelist yourmerchant_return_url
and get enabled with payment modes as required.
Payment Data [Child Object]
The table below lists the various parameters in the payment_data
child object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
amount_in_paisa | integer | M | The transaction amount in paisa. Example: 800 |
Txn Data [Child Object]
The table below lists the various parameters in the transaction_data
child object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
navigation_mode | integer | M | Checkout navigation mode. Example: 2 Accepted values:
|
payment_mode | string | M | The payment mode you prefer to accept payment. Accepted values:
|
transaction_type | integer | M | The type of transaction. Example: 1 Accepted values:
|
time_stamp | integer | O | Unix timestamp. Example: 157588000000 |
Customer Data [Child Object]
The table below lists the various parameters in the customer_data
child object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
email_id | string | O | Customer's email address. Example: [email protected] |
first_name | string | O | Customer's first name. Example: Kevin |
last_name | string | O | Customer's last name. Example: Bob |
customer_id | string | O | Unique identifier of the customer in Plural database. Example: 123456 |
mobile_no | string | O | Customer's mobile number. Example: 9876543210 |
billing_data | object | O | An object that contains the billing details. Learn more about our billing_data child object. |
shipping_data | object | O | An object that contains the shipping details. Learn more about our shipping_data child object. |
Billing Data [Child Object]
The table below lists the various parameters in the billing_data
child object. This is part of the customer_data
object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
address1 | string | O | Customer's billing address1. Example: No 10 Church street Bangalore |
address2 | string | O | Customer's billing address2. Example: No 10 Brigade road Bangalore |
address3 | string | O | Customer's billing address3. Example: No 10 M G road Bangalore |
pincode | string | O | Pincode of the billing address. Example: 560001 |
city | string | O | City of the billing address. Example: Bangalore |
state | string | O | State of the billing address. Example: Karanataka |
country | string | O | Country of the billing address. Example: India |
Shipping Data [Child Object]
The table below lists the various parameters in the shipping_data
child object. This is part of the customer_data
object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
address1 | string | O | Customer's shipping address1. Example: No 10 Church street Bangalore |
address2 | string | O | Customer's shipping address2. Example: No 10 Brigade road Bangalore |
address3 | string | O | Customer's shipping address3. Example: No 10 M G road Bangalore |
pincode | string | O | Pincode of the shipping address. Example: 560001 |
city | string | O | City of the shipping address. Example: Bangalore |
state | string | O | State of the shipping address. Example: Karanataka |
country | string | O | Country of the shipping address. Example: India |
Udf Data [Child Object]
The table below lists the various parameters in the udf_data
child object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
udf_field_1 | string | O | User defined value1. Example: Purchase |
udf_field_2 | string | O | User defined value2 Example: Purchase |
udf_field_3 | string | O | User defined value3. Example: Purchase |
udf_field_4 | string | O | User defined value4. Example: Purchase |
Product Details [Child Object]
The table below lists the various parameters in the product_details
child object.
Parameter | Type | Requirement Type | Description |
---|---|---|---|
product_code | string | M | The product code. Example: 7803 |
product_amount | string | M | The product amount. Example: 10000 |
Note:
- The sum of all the products
product_amount
must be equal to the total cart valuepayment_data.amount_in_paisa
.
- Encode JSON: Convert the updated JSON to a Base64 Encode. Use the below sample code to handle the conversion of the JSON to a Base64 Encode.
import java.util.Base64;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class SignatureGenerator {
private static Map < String, Object > clean(Map < String, Object > arr) {
return arr.entrySet().stream()
.filter(entry -> entry.getValue() != null && !entry.getValue().toString().isEmpty())
.collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
}
public static void main(String[] args) {
Map < String, Object > requestBody = new LinkedHashMap < > ();
Map < String, Object > merchant_data = new LinkedHashMap < > ();
merchant_data.put("merchant_id", "merchant_id");
merchant_data.put("merchant_access_code", "merchant_access_code");
merchant_data.put("unique_merchant_txn_id", "XYZ123");
merchant_data.put("merchant_return_url", "whitelisted_merchant_return_url");
requestBody.put("merchant_data", merchant_data);
Map < String, Object > paymentDataObject = new LinkedHashMap < > ();
paymentDataObject.put("amount_in_paisa", 100);
requestBody.put("payment_data", paymentDataObject);
Map < String, Object > txnObject = new LinkedHashMap < > ();
txnObject.put("navigation_mode", "2");
txnObject.put("payment_mode", "1,3,4,19,10,11,14");
txnObject.put("transaction_type", "1");
requestBody.put("txn_data", txnObject);
Map < String, Object > requestBodyCleaned = clean(requestBody);
Map < String, Object > mapStatus = new HashMap < > ();
mapStatus.put("result", requestBodyCleaned);
Gson gson = new GsonBuilder().disableHtmlEscaping().create();
String jsonString2 = gson.toJson(requestBodyCleaned);
jsonString2 = jsonString2.replace("\\/", "/");
// Encoding JSON string to base64
String base64Encoded = Base64.getEncoder().encodeToString(jsonString2.getBytes());
System.out.println(base64Encoded);
}
}
- HashMap: Generate HashMap using the Base64 Encode and the secret key. Use the below sample code to handle the generation of HashMap using SHA-256.
import java.io.UnsupportedEncodingException;
import java.math.BigInteger;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
public class SignatureGenerator {
public static String jsonHash(String request, String secret) throws NoSuchAlgorithmException, InvalidKeyException, IllegalStateException, UnsupportedEncodingException {
SecretKeySpec secretKeySpec = new SecretKeySpec(DatatypeConverter.parseHexBinary(secret), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(secretKeySpec);
byte[] hmacBytes = mac.doFinal(request.getBytes("UTF-8"));
String ss = String.format("%02x", new BigInteger(1, hmacBytes));
return bytesToHex(hmacBytes).toUpperCase();
}
private static String bytesToHex(byte[] bytes) {
StringBuilder result = new StringBuilder();
for (byte b : bytes) {
result.append(String.format("%02X", b));
}
return result.toString();
}
public static void main(String[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {
String responseBody = "<Base64EncodedPayload>";
String signingSecret = "<Secret>";
String requestSignature = SignatureGenerator.jsonHash(responseBody,signingSecret);
System.out.println(requestSignature);
}
}
2. Accept Payment
Use our accept payment API to generate the Plural hosted checkout link. Additionally, you need to pass the HashMap generated as the authorization header and the Base64 Encode in the request body of this API.
Use the below endpoint to Accept payment.
POST: https://uat.pinepg.in/api/v2/accept/payment
POST: https://pinepg.in/api/v2/accept/payment
Headers
You are required to pass this header in our Accept Payment API.
Key | Value |
---|---|
X-VERIFY | Use the generated HashMap, we use this to authenticate the API request. |
Shown below is a sample request and sample response for a Accept Payment API.
{
"request": "ewogICJtZXJjaGFudF9kYXRhIjogewogICAgIm1lcmNoYW50X2lkIjogMTA4NTA2LAogICAgIm1lcmNoYW50X2FjY2Vzc19jb2RlIjogIjRhOGM0MjJkLTkyOGMtNGY4My1iZmU4LTI3YTA5YWY2NjY0NyIsCiAgICAidW5pcXVlX21lcmNoYW50X3R4bl9pZCI6ICJYWVoxMjMiLAogICAgIm1lcmNoYW50X3JldHVybl91cmwiOiAiaHR0cDovLzE5Mi4xNjguMTAxLjkzOjcwNTAvQ2hhcmdpbmdSZXNwLmFzcHgiCiAgfSwKICAicGF5bWVudF9kYXRhIjogewogICAgImFtb3VudF9pbl9wYWlzYSI6IDgwMAogIH0sCiAgInR4bl9kYXRhIjogewogICAgIm5hdmlnYXRpb25fbW9kZSI6ICIyIiwKICAgICJwYXltZW50X21vZGUiOiAiMSwzLDQsMTksMTAsMTEsMTQiLAogICAgInRyYW5zYWN0aW9uX3R5cGUiOiAiMSIsCiAgICAidGltZV9zdGFtcCI6IDE1NzU4ODAwMDAwMAogIH0KfQ=="
}
{
"token": "S01NF8ntxnKu9E%2faXLt7ELcFH7NpfstrSj4jCTV91GHOvQ%3d",
"redirect_url": "https://pinepg.in/pinepg/v2/process/payment?token=S01NF8ntxnKu9E%2faXLt7ELcFH7NpfstrSj4jCTV91GHOvQ%3d",
"response_code": 1,
"response_message": "SUCCESS"
}
Refer to our Accept Payment API documentation for more information.
3. Handle Payment
Use the generated link returned in our accept payment API to redirect your customers to the plural hosted checkout page to accept payment. After successful payment we redirect your customers to your website.
Note:
- On successful payment we send the webhook event
payment.captured
and the status of the payment is updated toSUCCESS
.
3.1 Store Payment Details
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.
- It is recommended to validate the authenticity of the payment details returned. You can authenticate by verifying the signature.
Shown below is a sample callback response returned to the return URL.
{
"merchant_id": "106598",
"merchant_access_code": "4a39a6d4-46b7-474d-929d-21bf0e9ed607",
"unique_merchant_txn_id": "TestNode3222",
"pine_pg_txn_status": "4",
"txn_completion_date_time": "18/03/2024 04:44:49 PM",
"amount_in_paisa": "1000",
"txn_response_code": "1",
"txn_response_msg": "SUCCESS",
"acquirer_name": "BILLDESK",
"pine_pg_transaction_id": "14635747",
"captured_amount_in_paisa": "1000",
"refund_amount_in_paisa": "0",
"payment_mode": "3",
"mobile_no": "",
"udf_field_1": "",
"udf_field_2": "",
"udf_field_3": "",
"udf_field_4": "",
"Acquirer_Response_Code": "0300",
"Acquirer_Response_Message": "DEFAULT",
"parent_txn_status": "",
"parent_txn_response_code": "",
"parent_txn_response_message": "",
"dia_secret": "156A7BD91DCC0A7BD9D080FDC900581A7BC65D8B17A535E24CE6A042B93DF7C9",
"dia_secret_type": "SHA256"
}
Refer to the below table to know the status of the transaction through the sample callback response.
PinePGTxnStatus | TxnResponseCode | Transaction Status |
---|---|---|
4 | 1 | Success |
1 | 0 | To know the status of the transaction please use our Inquiry API. |
-7 | Any Code | Failed |
Note:
- Signature is sent against
dia_secret
key use this signature to verify the payment.
3.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 a transaction. Follow the below steps to verify the payment signature.
- Generate a signature on your server using the response callback with the SHA256 algorithm. Follow the below steps to generate a signature.
- Remove
dia_secret
anddia_secret_type
from the response callback returned to the return URL. - Sort the remaining payload in alphabetical order.
- Convert the sorted payload into a string with values separated by
&
. - Use the string generated with the MID secret to create a signature using the SHA256 algorithm.
- Remove
The samples for the above steps are shown below.
{
"merchant_id": "106598",
"merchant_access_code": "4a39a6d4-46b7-474d-929d-21bf0e9ed607",
"unique_merchant_txn_id": "TestNode3222",
"pine_pg_txn_status": "4",
"txn_completion_date_time": "18/03/2024 04:44:49 PM",
"amount_in_paisa": "1000",
"txn_response_code": "1",
"txn_response_msg": "SUCCESS",
"acquirer_name": "BILLDESK",
"pine_pg_transaction_id": "14635747",
"captured_amount_in_paisa": "1000",
"refund_amount_in_paisa": "0",
"payment_mode": "3",
"mobile_no": "",
"udf_field_1": "",
"udf_field_2": "",
"udf_field_3": "",
"udf_field_4": "",
"Acquirer_Response_Code": "0300",
"Acquirer_Response_Message": "DEFAULT",
"parent_txn_status": "",
"parent_txn_response_code": "",
"parent_txn_response_message": ""
}
Acquirer_Response_Code=0300
Acquirer_Response_Message=DEFAULT
acquirer_name=BILLDESK
amount_in_paisa=1000
captured_amount_in_paisa=1000
merchant_access_code=4a39a6d4-46b7-474d-929d-21bf0e9ed607
merchant_id=106598
mobile_no=
parent_txn_response_code=
parent_txn_response_message=
parent_txn_status=
payment_mode=3
pine_pg_transaction_id=14635747
pine_pg_txn_status=4
refund_amount_in_paisa=0
txn_completion_date_time=18/03/2024 04:44:49 PM
txn_response_code=1
txn_response_msg=SUCCESS
udf_field_1=
udf_field_2=
udf_field_3=
udf_field_4=
unique_merchant_txn_id=TestNode3222
Acquirer_Response_Code=0300&Acquirer_Response_Message=DEFAULT&acquirer_name=BILLDESK&amount_in_paisa=1000&ca
ptured_amount_in_paisa=1000&merchant_access_code=4a39a6d4-46b7-474d-929d21bf0e9ed607&merchant_id=106598&mobile_no=&parent_txn_response_code=&parent_txn_response_message=&parent_txn_
status=&payment_mode=3&pine_pg_transaction_id=14635747&pine_pg_txn_status=4&refund_amount_in_paisa=0&txn_compl
etion_date_time=18/03/2024 04:44:49
PM&txn_response_code=1&txn_response_msg=SUCCESS&udf_field_1=&udf_field_2=&udf_field_3=&udf_field_4=&unique_merc
hant_txn_id=TestNode3222
- 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;
}
}
- If the signature generated on your server matches the Plural signature returned against the
dia_secret
key, it confirms that the payment details are from Plural. - Capture the status returned on your database.
Know Your Payment Status
You can know the status of the payment using the below.
- Webhook Notification: We send Webhook notifications on the successful payment or any changes to the payments object.
{
"event_name": "payment.captured",
"merchant_response": {
"merchant_id": "29792",
"payment_mode": "EMI",
"merchant_access_code": "d860a376-2182-4448-9d87-2b2c752b8991",
"unique_merchant_txn_id": "c-947711168513-03070150-1",
"pine_pg_txn_status": "4",
"txn_completion_date_time": "03/03/2024 12:33:02 PM",
"product_code": "273865",
"captured_amount_in_paisa": "13559000",
"refund_amount_in_paisa": "0",
"txn_response_code": "1",
"amount_in_paisa": "14059000",
"txn_response_msg": "SUCCESS",
"acquirer_name": "HDFC_FSS_IN_HOUSE",
"pine_pg_transaction_id": "294774500",
"rrn": "406358019945",
"auth_code": "055712",
"masked_card_number": "************2562",
"card_holder_name": "name",
"mobile_no": "9810505359",
"salted_card_hash": "651BB095DE12C950EF09401518017A06C5DC1A1FE5D0E7782A373F7CFB5482A3",
"udf_field_1": "110014C25 1st FloorJangpura extension jangpura new delhiDELHIDELHI",
"udf_field_2": "492001Hudco Regional Office 1B Surya ApartmentsKatora Talab Civil Lines RaipurRAIPURCHHATTISGARH",
"udf_field_3": "273865",
"udf_field_4": "01eae2ec05761000bbea86e16dcb4b79CROMA41646",
"emi_tenure_month": "1",
"emi_interest_rate_percent": "0.00",
"emi_principal_amount_in_paisa": "13559000",
"emi_amount_payable_each_month_in_paisa": "0",
"is_brand_emi_txn": "1",
"emi_cashback_type": "0",
"parent_txn_status": "",
"parent_txn_response_code": "",
"parent_txn_response_message": "",
"issuer_name": "HDFC",
"product_category": "MacBook Air",
"manufacturer": "Apple Macbook",
"product_discount": "500000"
}
}
Note:
Webhooks are asynchronous, so for time-sensitive actions, we recommend polling our Inquiry API.
- Inquiry API
Use this API to retrieve the status of the specified payment.
Use the below endpoint to retrieve the status of the Payment.
PSOT: https://uat.pinepg.in/api/PG/v2
PSOT: https://pinepg.in/api/PG/v2
Shown below is a sample request and sample response for a Inquiry API.
ppc_DIA_SECRET=DECF2D9D903BACAF85DA88B5686BC0FB6AB7681673E99191C86B4DC78C27277F&ppc_
DIA_SECRET_TYPE=SHA256&ppc_MerchantAccessCode=58ad283b-7c93-4f19-b072- b17e8ecfb20e&ppc_MerchantID=2415&ppc_TransactionType=3&ppc_UniqueMerchantTxnID=100000000000007687
{
"ppc_MerchantID": "279082",
"ppc_MerchantAccessCode": "cfd05c0c-39f1-4232-bd6f-6d3a8608e1be",
"ppc_PinePGTxnStatus": "7",
"ppc_TransactionCompletionDateTime": "17/07/2024 12:41:54 PM",
"ppc_UniqueMerchantTxnID": "testingedgeseamless1123145432",
"ppc_Amount": "100",
"ppc_TxnResponseCode": "1",
"ppc_TxnResponseMessage": "SUCCESS",
"ppc_PinePGTransactionID": "342048376",
"ppc_CapturedAmount": "100",
"ppc_RefundedAmount": "0",
"ppc_AcquirerName": "KOTAK_SETU",
"ppc_DIA_SECRET": "9FFA2E99D14B6357E50D9AF2CF9D01D67B03FA1020BB88A82E76C962313FC004",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_PaymentMode": "10",
"ppc_Parent_TxnStatus": "4",
"ppc_ParentTxnResponseCode": "1",
"ppc_ParentTxnResponseMessage": "SUCCESS",
"ppc_UdfField1": "",
"ppc_UdfField2": "",
"ppc_UdfField3": "",
"ppc_UdfField4": "",
"ppc_RRN": "1721200204930238149",
"ppc_AcquirerResponseCode": "SUCCESS",
"ppc_AcquirerResponseMessage": "SUCCESS"
}
Updated 2 months ago