Prerequisite

Learn about the prerequisites of our Accept payment and Inquiry/Refund API.

Accept Payment API

Plural accept payment API use Base64 Encode as an input request. And use HashMap to authorise the payment.

  1. Enter Payment Details: Enter the payment and merchant details using the sample JSON payload.
  2. Encode JSON: Use the payment and merchant details updated JSON to convert to a Base64 Encode.
  3. HashMap: Along with the Base64 Encode pass the secret key and generate an HashMap secret.

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 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:
  • 10: For UPI.
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.

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", "7");
    txnObject.put("payment_mode", "10");
    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 secret key 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);
    }
} 

Inquiry/Refund API

As a pre-requisite you must generate the HashMap secret key to pass against the ppc_DIA_SECRET parameter of the Inquiry/Refund API request.

Follow the below steps to generate a HashMap secret key.

  1. Use the & separated payload format provided below to enter the transaction details you wish to Inquire about.
ppc_MerchantAccessCode=cfd05c0c-39f1-4232-bd6f-6d3a8608e1be&ppc_MerchantID=279082&ppc_TransactionType=3&ppc_UniqueMerchantTxnID=testingedgeseamless1123145432
ppc_Amount=100&ppc_CurrencyCode=356&ppc_MerchantAccessCode=bcf441be-411b-46a1-aa88-c6e852a7d68c&ppc_MerchantID=106600&ppc_PinePGTransactionID=14709745&ppc_TransactionType=10&ppc_UniqueMerchantTxnID=refund%20test

📘

Note:

  • The HashMap payload is sorted alphabetically by the key names. Please ensure you use the same order of key-value pairs as provided in the payload to generate a HashMap secret.
  1. Use the sample code provided below to generate a SHA256 Hash.
  2. In the sample code use the respective HashMap payload based on the operations you want to perform, with updated transaction details along with your secret key to generate a SHA256 Hash.
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 = "<HashMap_payload>";
        String signingSecret = "<Secret_key>";

        String requestSignature = SignatureGenerator.jsonHash(responseBody,signingSecret);
        System.out.println(requestSignature);
    }
}
  1. Use the generate HashMap secret against the ppc_DIA_SECRET in the Inquiry/Refund request.