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.
- Enter Payment Details: Enter the payment and merchant details using the sample JSON payload.
- Encode JSON: Use the payment and merchant details updated JSON to convert to a Base64 Encode.
- 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.
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", "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.
- 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.
- Use the sample code provided below to generate a SHA256 Hash.
- 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);
}
}
- Use the generate HashMap secret against the
ppc_DIA_SECRET
in the Inquiry/Refund request.