Product Guides

Integration Steps

Learn how you can integrate with Plural APIs to start accepting payments on your website.

Suggest Edits

Follow the below steps to integrate with Plural seamless checkout APIs in your application.

  1. Prerequisite.
  2. Accept Payment.
  3. Process Payment.
    1. Cards.
    2. UPI.
    3. Net Banking.
    4. Wallets.
  4. Handle Payments.
    1. Store Payment Details.
    2. Verify Payment Signature.

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": "10",
    "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 udf_data child object.
product_detailsarray of objectOAn 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.

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:
  • 1: CREDIT/DEBIT CARD
  • 3: NET BANKING
  • 4:CREDIT EMI
  • 10: UPI
  • 11: WALLET
  • 14: DEBIT EMI
  • 16: PREBOOKING
  • 17: BNPL/FLEXIPAY
  • 19: Cardless EMI
  • 20: PBP (Paybypoints)
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 billing_data child object.
shipping_dataobjectOAn 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.

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. Process Payment API

Use this API process a Payment. You can use the same API to process a payment using the below methods of payment.

  • Card Payment
  • UPI Payment
  • Net Banking
  • Wallet

📘

Note:

  • Ensure that you use the appropriate payloads corresponding to the specific payment methods for which you want to initiate a request.
  • We also verify the payment method provided in the "Accept Payment" request before processing the process payment.

Use the below endpoints to Process a Payment.

POST: https://uat.pinepg.in/api/v2/accept/payment

POST: https://pinepg.in/api/v2/accept/payment

Query Parameter

Token: You need to pass the token generated in the Accept Payment API as the query parameter.

1. Cards

🚧

Watch Out

  • To Integrate with Plural seamless checkout flow you must have a PCI compliance certificate.

Shown below is a sample request and sample response for a Process Payment API via Cards.

{
  "card_data": {
    "card_number": "4012001037141112",
    "card_expiry_year": "2030",
    "card_expiry_month": "12",
    "card_holder_name": "Test",
    "cvv": "123"
  }
}

Sample Request

Click Here

The table below lists all the request parameters.

ParameterTypeRequirement TypeDescription
card_dataobjectMAn object that contains the card details.

Learn more about our card_daata child object.
Card Data [Child Object]

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

ParameterTypeRequirement TypeDescription
card_numberstringMCard Number.

Example: 123456789012

Supported characters: 0-9
card_expiry_yearstringMCard expiry year as on the card.

Has to be 4 digits.

Example: 2024

Supported characters: 0-9
card_expiry_monthstringMCard expiry month as on the card.

Has to be 2 digits.

Example: 08

Supported characters: 0-9
card_holder_namestringMCard holder name.

Example: Kevin
cvvstringMCard Verification Value [cvv] of the card.

Example: 123

Supported characters: 0-9

2. UPI

UPI Payments can be further categorized into two types: Collect and Intent. You can use this process payment API to process both Collect and Intent payment requests.

UPI Intent

Shown below is a sample request and sample response for a Process Payment API via UPI Intent flow.

{
  "upi_data": {
    "upi_option": "UPI",
    "txn_mode": "INTENT"
  }
}

{
  "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"
}

UPI Collect

Shown below is a sample request and sample response for a Process Payment API via UPI Collect flow.

{
  "upi_data": {
    "vpa": "test@upi",
    "upi_option": "UPI "
  }
}

{
  "response_code": 1,
  "response_message": "SUCCESS"
}
Sample Request
Click Here

The table below lists all the request parameters.

ParameterTypeRequirement TypeDescription
upi_dataobjectMAn object that contains the UPI details.

Learn more about our upi_data child object.

UPI Data [Child Object]

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

ParameterTypeRequirement TypeDescription
upi_optionstringMUPI Payment options.

Accepted values:
  • UPI
  • GPAY
txn_modestringCTransaction mode of the UPI payment.

Accepted value: INTENT

Note: Mandatory for UPI intent payment.
vpastringCVPA handle of your customer's.

Example: [email protected]

Note: Mandatory for UPI Collect payment.

3. Net Banking

Shown below is a sample request and sample response for a Process Payment API via Net Banking.

{
  "netbanking_data": {
    "pay_code": "NB1493"
  }
}

{
  "response_code": 1,
  "response_message": "SUCCESS",
  "redirect_url": "http://hostname:port/pinepg/v2/process/payment?token=848RFsu%2bRnNcSsaZdzEgkeosvCc2o5lK TV4uKJF%2fcjE%3d"
}

Sample Request

Click Here

The table below lists all the request parameters.

ParameterTypeRequirement TypeDescription
netbanking_dataobjectMAn object that contains the Net Bankding details.

Learn more about our netbanking_data child object.

Netbanking Data [Child Object]

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

ParameterTypeRequirement TypeDescription
pay_codestringMPayment codes of corresponding Banks.

Example: NB1493

The table below lists the various pay codes of the corresponding Banks.

Pay CodeBank Name
NB1148Kotak Bank
NB1378Andhra Bank
NB1484Andhra Bank Corporate
NB1530Allahabad Bank
NB1529AU Small Finance Bank
NB1485Bank of Baroda - Corporate Banking
NB1486Bank of Bahrain and Kuwait
NB1487Bank of Baroda - Retail Banking
NB1511Bassien Catholic Coop Bank
NB1533Bandhan Bank - Corporate
NB1508Bandhan Bank
NB1229Bank of Maharashtra
NB1527Barclays Bank - Corporate Net Banking
NB1147Central Bank
NB1224Canara Bank
NB1488Cosmos Bank
NB1489Punjab National Bank - Corporate Banking
NB1523Corporation Bank - Corporate
NB1135Corporation Bank
NB1272Catholic Syrian Bank
NB1215City Union Bank
NB1490Deutsche Bank
NB1509Digibank by DBS
NB1491Development Credit Bank
NB1492Dena Bank
NB1526Dhanlaxmi Bank Corporate
NB1373Dhanalakshmi Bank
NB1515Equitas Small Finance Bank
NB1518ESAF Small Finance Bank
NB1029Federal Bank
NB1532Fincare Bank - Retail
NB1007HDFC Bank
NB1016ICICI Bank
NB1493IDBI Bank
NB1521IDBI Corporate
NB1510IDFC FIRST Bank
NB1431IndusInd Bank
NB1143Indian Bank
NB1213Indian Overseas Bank
NB1015JK Bank
NB1503Janata Sahakari Bank Ltd Pune
NB1133Karnataka Bank
NB1506Kalyan Janata Sahakari Bank
NB1514The Kalupur Commercial Co-Operative Bank
NB1494Karur Vysya Bank
NB1495Laxmi Vilas Bank - Corporate Net Banking
NB1496Laxmi Vilas Bank - Retail Net Banking
NB1507Mehsana urban Co-op Bank
NB1520North East Small Finance Bank Ltd
NB1504NKGSB Co-op Bank
NB1154Oriental Bank of Commerce
NB1534Karnataka Gramin Bank
NB1497Punjab & Maharashtra Co-op Bank
NB1381Punjab National Bank
NB1512PNB Yuva Netbanking
NB1421Punjab and Sindh Bank
NB1513RBL Bank Limited
NB1524RBL Bank Limited - Corporate Banking
NB1531State bank Of India
NB1498Standard Chartered Bank
NB1499South Indian Bank
NB1517Suryoday Small Finance Bank
NB1525Shamrao Vithal Co-op Bank - Corporate
NB1500Shamrao Vithal Co-op Bank
NB1380Saraswat Bank
NB1501Syndicate Bank
NB1516Thane Bharat Sahakari Bank Ltd
NB1505TJSB Bank
NB1439Tamilnad Mercantile Bank
NB1502Tamil Nadu State Co-operative Bank
NB1216Union Bank of India
NB1483UCO Bank
NB1212United Bank Of India
NB1004AXIS Bank
NB1379Vijaya Bank
NB1519Varachha Co-operative Bank Limited
NB1522Yes Bank Corporate
NB1146Yes Bank

4. Wallets

Shown below is a sample request and sample response for a Process Payment API via Wallets.

{
  "wallet_data": {
    "wallet_code": "payzapp",
    "mobile_number": "9899189287"
  }
}

{
  "response_code": 1,
  "response_message": "SUCCESS",
  "redirect_url": "http://hostname:port/pinepg/v2/process/payment?token=848RFsu%2bRnNcSsaZdzEgkeosvCc2o5lK TV4uKJF%2fcjE%3d"
}

Sample Request

Click Here

The table below lists all the request parameters.

ParameterTypeRequirement TypeDescription
wallet_dataobjectMAn object that contains the Wallet details.

Learn more about our wallet_data child object.

Wallet Data [Child Object]

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

ParameterTypeRequirement TypeDescription
wallet_codestringMUnique code of the wallet.

Accepted values:
  • OXY: Oxygen
  • PAYTM: Paytm
  • PAYZAPP: PayZapp
  • PHONEPE: PhonePe
mobile_numberstringMRegistered mobile number of the wallet.

Example: 9876543210

Refer to our Process Payment API Documentation for more information.

4. 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 to SUCCESS.

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

PinePGTxnStatusTxnResponseCodeTransaction Status
41Success
10To know the status of the transaction please use our Inquiry API.
-7Any CodeFailed

📘

Note:

  • Signature is sent against dia_secret key use this signature to verify the payment.

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 a transaction. Follow the below steps to verify the payment signature.

  1. Generate a signature on your server using the response callback with the SHA256 algorithm. Follow the below steps to generate a signature.
    1. Remove dia_secret and dia_secret_type from the response callback returned to the return URL.
    2. Sort the remaining payload in alphabetical order.
    3. Convert the sorted payload into a string with values separated by &.
    4. Use the string generated with the MID secret to create a signature using the SHA256 algorithm.

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
  1. 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;
    }
}
  1. If the signature generated on your server matches the Plural signature returned against the dia_secretkey, it confirms that the payment details are from Plural.
  2. Capture the status returned on your database.

Know Your Payment Status

You can know the status of the payment using the below.

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