Seamless UPI Integration Flow
Learn how to integrate with Plural APIs to use Plural Third Party Validation.
By Integrating with Plural's Third Party Validation (TPV), you can ensure transaction are made from the pre registered bank accounts through conditional validation checks. Seamlessly comply with SEBI guidelines for secure online payments. Provide seamless payment experience using UPI.
The figure below shows the step by step procedure for integrating with Plural Third Party Validation(TPV).

- Prerequisite: Our accept payment API use Base64 Encode as an input request. And use Hashmap to authorize the payment.
- Enter Payment Details: Enter the payment and merchant details using the sample JSON payload.
- Encode JSON: Use the updated payment and merchant details JSON to convert to a Base64 Encode.
- Hashmap: Along with the Base64 Encode pass the secret key and generate an HashMap secret.
- Accept Payment: Integrate our Accept Payment API in you Backend server and use this API to initiate a payment.
- Generate Payment Link: Integrate our Generate Payment Link API in your Backend and use this API to generate a Payment Link.
Note:
Handle Payment: After generating the URL, Use this Link to navigate your customer's to their mobile apps. You can do this by rendering the URL returned by Plural as a button or a link for the customer to use.
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": "7",
"payment_mode": "10",
"transaction_type": "1",
"time_stamp": 157588000000
}
}
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 merchant_data child object. |
product_details | array of object | O | An object that contains the array of product details. Learn more about our merchant_data 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 a 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: 7 Accepted values:
Note: Currently TPV is available through Seamless checkout only. |
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. 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 merchant_data child object. |
shipping_data | object | O | An object that contains the shipping details. Learn more about our merchant_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: DD |
udf_field_2 | string | O | User defined value2 Example: XOF |
udf_field_3 | string | O | User defined value3. Example: XOA |
udf_field_4 | string | O | User defined value4. Example: ASDF |
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 SHA256.
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 API
Use this API to generate a token against a payment.
Use the below Endpoints to accept payment.
POST: https://uat.pinepg.in/api/v2/accept/payment
POST: https://pinepg.in/api/v2/accept/payment
Shown below are the sample request and sample response for a Accept Payment API.
{
"request": "ewogICJtZXJjaGFudF9kYXRhIjogewogICAgIm1lcmNoYW50X2lkIjogMjIyMDgyLAogICAgIm1lcmNoYW50X2FjY2Vzc19jb2RlIjogImNmZDA1YzBjLTM5ZjEtNDIzMi1iZDZmLTZkM2E4NjA4ZTFiZSIsCiAgICAidW5pcXVlX21lcmNoYW50X3R4bl9pZCI6ICJ0ZXN0aW5nZWRnZXNlYW1sZXNzMTEyMzQ1NDMyIiwKICAgICJtZXJjaGFudF9yZXR1cm5fdXJsIjogImh0dHBzOi8vc3RhZ2Utd2ViYXBwLnBheXRtLmluL3Blb24ucGhwIgogIH0sCiAgInBheW1lbnRfZGF0YSI6IHsKICAgICJhbW91bnRfaW5fcGFpc2EiOiA4MDAKICB9LAogICJ0eG5fZGF0YSI6IHsKICAgICJuYXZpZ2F0aW9uX21vZGUiOiAiNyIsCiAgICAicGF5bWVudF9tb2RlIjogIjEwIiwKICAgICJ0cmFuc2FjdGlvbl90eXBlIjogIjEiLAogICAgInRpbWVfc3RhbXAiOiAxNTc1ODgwMDAwMDAKICB9Cn0="
}
{
"token": "S087B99vA68R0L9gb8JI%2bqjds%2bOZaArBKLb3s7eQ%2fg7k%3d",
"response_code": 1,
"response_message": "SUCCESS"
}
Refer to our Accept Payment API Documentation for more information.
3. Generate Payment Link
To Generate a Payment Link use our Generate Payment Link API.
Use the below endpoints to Generate a Payment Link.
POST: https://uat.pinepg.in/api/v2/process/payment
POST: https://pinepg.in/api/v2/process/payment
Query Parameter
Token
: You need to pass the token generated in the Accept Payment API as the query parameter.
Shown below is a sample request and sample response for a Generate Payment Link API.
{
"upi_data": {
"upi_option": "UPI",
"txn_mode": "INTENT"
},
"bank_account": {
"account_number": "00000037990853412",
"name": "HDFC",
"ifsc": "HDFC0000053"
}
}
{
"pg_upi_unique_request_id": "170724PLPre22116284",
"deep_link": "upi://pay?pa=pl.pinelabs@pineaxis&pn=Pinelabs%20Private%20Limited%20dummy&am=8.00&mam=8.00&tr=SU01J2ZMXHX4PVBVASQJPBG2XW6V&tn=Payment%20for%20342027241&cu=INR&mc=7399",
"pine_pg_transaction_id": 342027241,
"short_link": "https://upipay.setu.co/nO6yP65XUmwh",
"response_code": 1,
"response_message": "SUCCESS"
}
Refer to our Generate Payment Link API Documentation for more information.
Watch Out:
- For PNB accounts, pass 16-digit account numbers with a prefix zero.
Example: If the account number is 123456789012345, pass it as 0123456789012345.- For PSBI, Canara, CITI and SBI accounts, pass 17-digit account numbers with a prefix zero.
Example: If the account number is 1234567890123456, pass it as 01234567890123456.- For all other banks, pass the account number as is.
Handle Payments
Use the generated link returned in our Generate Payment Link API to redirect your customers to the seamless checkout to accept payment.
To know the status of the payment you can use the below options.
- Inquiry API: Use this API to check transaction statuses.
- Webhook Notification: We send Webhook notifications on the successful payment or any changes to the payments response object.
Updated 7 months ago