Seamless NetBanking 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 Netbanking.

The figure below shows the step-by-step procedure for integrating with Plural Third Party Validation (TPV).

  1. Prerequisite: Our accept payment API use Base64 Encode as an input request. And use HashMap to authorize the payment.
    1. Enter Payment Details: Enter the payment and merchant details using the sample JSON payload.
    2. Encode JSON: Use the updated payment and merchant details JSON to convert to a Base64 Encode.
    3. HashMap: Along with the Base64 Encode pass the secret key and generate an HashMap secret.
  2. Accept Payment: Integrate our Accept Payment API in you Backend server and use this API to initiate a payment.
  3. 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 customers 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

  1. Enter Payment Details: Use the below JSON to enter the payment Details. You are required to enter the merchant_data and payment_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": "3",
    "transaction_type": "1",
    "time_stamp": 157588000000
  }
}

JSON Parameters

Click Here

The table below lists the various JSON parameters.

ParameterTypeRequirement TypeDescription
merchant_dataobjectMAn object that contains the merchant details.

Learn more about our merchant_data child object.
payment_dataobjectMAn object that contains the payment details.

Learn more about our payment_data child object.
txn_dataobjectMAn object that contains the transaction details.

Learn more about our txn_data child object.
customer_dataobjectOAn object that contains the customer details.

Learn more about our customer_data child object.
udf_dataobjectOAn object that contains the user defined details.

Learn more about our merchant_data child object.
product_detailsarray of objectOAn 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.

ParameterTypeRequirement TypeDescription
merchant_idintegerMUnique identifier of the merchant in the Plural database.

Example: 123456
merchant_access_codestringMUnique merchant access code provided by Plural.

Example: 4a8c422e-928d-4f84-bfe8-27a09af66647
unique_merchant_txn_idstringMUnique identifier of the specific transaction.

Example: xyz123
merchant_return_urlstringMMerchant 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 and merchant_access_code. Additionally you are required to whitelist your merchant_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.

ParameterTypeRequirement TypeDescription
amount_in_paisaintegerMThe transaction amount in paisa.

Example: 800

Txn Data [Child Object]

The table below lists the various parameters in the transaction_data child object.

ParameterTypeRequirement TypeDescription
navigation_modeintegerMCheckout navigation mode.

Example: 7

Accepted values:
  • 2: For Redirect Checkout.
  • 7: For Seamless Checkout.


Note: Currently TPV is available through Seamless checkout only.
payment_modestringMThe payment mode you prefer to accept payment.

Accepted values:
  • 3: For Netbanking.
transaction_typeintegerMThe type of transaction.

Example: 1

Accepted values:
  • 1: For Purchase.
time_stampintegerOUnix timestamp.

Example: 157588000000

Customer Data [Child Object]

The table below lists the various parameters in the customer_data child object.

ParameterTypeRequirement TypeDescription
email_idstringOCustomer's email address.

Example: [email protected]
first_namestringOCustomer's first name.

Example: Kevin
last_namestringOCustomer's last name.

Example: Bob
customer_idstringOUnique identifier of the customer.

Example: 123456
mobile_nostringOCustomer's mobile number.

Example: 9876543210
billing_dataobjectOAn object that contains the billing details.

Learn more about our merchant_data child object.
shipping_dataobjectOAn 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.

ParameterTypeRequirement TypeDescription
address1stringOCustomer's billing address1.

Example: No 10 Church street Bangalore
address2stringOCustomer's billing address2.

Example: No 10 Brigade road Bangalore
address3stringOCustomer's billing address3.

Example: No 10 M G road Bangalore
pincodestringOPIncode of the billing address.

Example: 560001
citystringOCity of the billing address.

Example: Bangalore
statestringOState of the billing address.

Example: Karanataka
countrystringOCountry 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.

ParameterTypeRequirement TypeDescription
address1stringOCustomer's shipping address1.

Example: No 10 Church street Bangalore
address2stringOCustomer's shipping address2.

Example: No 10 Brigade road Bangalore
address3stringOCustomer's shipping address3.

Example: No 10 M G road Bangalore
pincodestringOPIncode of the shipping address.

Example: 560001
citystringOCity of the shipping address.

Example: Bangalore
statestringOState of the shipping address.

Example: Karanataka
countrystringOCountry of the shipping address.

Example: India

Udf Data [Child Object]

The table below lists the various parameters in the udf_data child object.

ParameterTypeRequirement TypeDescription
udf_field_1stringOUser defined value1.

Example: DD
udf_field_2stringOUser defined value2

Example: XOF
udf_field_3stringOUser defined value3.

Example: XOA
udf_field_4stringOUser defined value4.

Example: ASDF

Product Details [Child Object]

The table below lists the various parameters in the product_details child object.

ParameterTypeRequirement TypeDescription
product_codestringMThe product code.

Example: 7803
product_amountstringMThe product amount.

Example: 10000

📘

Note:

  • The sum of all the products product_amount must be equal to the total cart value payment_data.amount_in_paisa.
  1. 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);
  }
}
  1. 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.

{
  "netbanking_data": {
    "pay_code": "NB1535"
  },
  "tpv_data": {
    "account_number": "1234567890123456",
    "name": "Kenin",
    "ifsc": ""
  }
}
{
  "redirect_url": "https://uat.pinepg.in/pinepg/v2/process/payment?token=S01VHxGYfOhZdIEej6%2fKIZ88MiRRxF6vL8HdnOjLKDt2CY%3d",
  "response_code": 1,
  "response_message": "SUCCESS"
}

Refer to our Generate Payment Link API Documentation for more information.

📘

Note:

  • 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, and CITI 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.

  1. Inquiry API: Use this API to check transaction statuses.
  2. Webhook Notification: We send Webhook notifications on the successful payment or any changes to the payment's response object.