Sorry, your browser does not support JavaScript! API References - Payment Gateway | Pine Labs

Payment Gateway

Introduction

Pine Labs Payment Gateway brings the rich set of payment offerings to the online world.

This includes multi-acquiring, Brand EMI along with many other features.

This page will explain how to integrate merchant's website with Pine Labs Payment Gateway and use the payment gateway service. It is intended for users who want to carry out integration with payment gateway. It covers the steps in the payment process and the information that needs to be passed from merchant's server to Pine Labs Payment Gateway, to enable payment processing.

Getting Started

Pine Labs Payment Gateway is a secure website, where customer is redirected from merchant's website to make a payment. The payment gateway collects customer card details to process the payment transaction.

After the payment is complete, the customer is returned to merchant's website along with payment details.

Transaction Flow

Pine Labs Payment Gateway will enable your website to receive payment from customers via multiple modes such as card, net banking, wallets, UPI and others.

When customer selects Make Payment at your website, it redirects to the Pine Labs Payment Gateway page. During redirection, your page needs to submit information about the payment, such as your merchant id (MID), amount to be paid and other relevant information.

A simplified illustration of the transaction flow is shown in Figure 1 below.

payment payment
  1. Customer does online E- commerce Shopping
  2. Customer selects product from merchant page
  3. Customer makes payment through Pine Labs Payment Gateway.
  4. Acquirer/Issuer bank authorizes the transaction and sends response to Pine Labs Payment Gateway.
  5. Pine Labs Payment Gateway shares payement status and product details to E- commerce store.
  6. E- Commerce store shares response to customer. sresponse to Pine Labs Payment Gateway.

Payment Process

Figure 2: below provides a more detailed view of the interaction between customer, merchant and Pine Labs Payment Gateway in a typical transaction

payment payment

Steps of the Payment

Payment details are collected from the customer and you are notified of the results in the following steps:

  1. Customer selects the product and proceeds to pay, your website redirects the customer to Pine Labs Payment Gateway.
  2. The customer selects the payment mode and enters card details to initiate the transaction. The customer will be re-directed to 3DES authentication page and will be verified by Visa / MasterCard SecureCode /
  3. The customer will be re-directed to 3DES authentication page and will be verified by Visa / MasterCard SecureCode / Amex Safe key. On successful authentication Pine Labs Payment Gateway seeks authorisation of the payment.

Payment Models

Pine Labs Payment Gateway supports the following payment models:

  • Purchase
  • Pre-Auth & Capture

The Merchant can be enrolled for pre-auth & capture payment model or purchase payment model.

A merchant cannot have both the payment models on a single MID.

Transaction Types

This section provides the details regarding the transaction types that are supported. Payment Gateway supports the following transaction types:

  • Purchase
  • Refund
  • Enquiry
  • Pre-Auth
  • Capture
Purchase

In purchase transaction the authorization by issuing bank and debit from customer account takes place in a single step. Visit our GitHub page for integration details and test data.

Pre-Auth & Capture

Pre-Auth (commonly referred to as Authorization) transaction, wherein the transaction value of the goods or services is sent to the issuing bank to verify the funds availability in the customer card account and to block the (Open To Buy -OTB) funds until the Capture transaction is initiated by the merchant.

The Pre-Auth transaction blocks the funds in the card account for a pre-defined period of time as determined by the issuing bank

The Pre-Auth transaction should be followed by Capture transaction independently.

The Capture transaction refers to the initial Pre-Auth transaction. Issuing bank transfers the funds from customer card account through the acquiring bank to the merchant's bank account. Visit our GitHub page for integration details and test data.

Dependent Transactions

For every authorized transaction, there may be a number of associated supporting financial transactions.

Example:
  • Enquiry to know the status of the transaction.
  • Refund for Purchase transaction.
  • Refund for Pre-Auth/Capture transaction.
Refund and Enquiry

The Refund API gives the convenience of automating customer refunds.

If for some reason you didn't receive a response from Pine Labs Payment Gateway for a Sale or Refund transaction (maybe the user abandoned the transaction midway or there was a network/timeout issue when Pine Labs Payment Gateway sent the response to callback URL).

Merchant can use the Enquiry API to confirm the final status of the transaction. This transaction can be initiated from Pine Labs Payment Gateway API.

Integration Modes

Following integration modes are supported:

  • Redirect
  • Seamless

Merchant redirects a customer to Pine Labs Payment Gateway landing page. This is called re-direct mode.

Capturing customer card details at merchant page is called seamless mode. In this case, merchant needs to be PCI DSS certified..

Redirect

Merchant redirects customer to Pine Labs Payment Gateway landing page along with merchant and other specific details.

Customer enters card details on Pine Labs Payment Gateway page.

Pine Labs Payment Gateway processes transactions by communicating with Acquirer in turn scheme and then Issuer banks.

After transaction completion, Pine Labs Payment Gateway maps transaction with Merchant and order specific details and redirects customer to merchant page along with the response of the transaction.

In redirect mode, landing page can be customized for a merchant.

Fonts, logo and color scheme of Pine Labs Payment Gateway page can be merchant specific. So that when a customer gets redirected from merchant site to Pine Labs Payment Gateway page, seamless experience is offered in terms of look and feel of website.

Seamless

In this integration mode, merchant captures card details of the customer at his/her page and calls Pine Labs Payment Gateway API passing encrypted card details along with merchant and other specific fields.

Pine Labs Payment Gateway processes this transaction, maps transaction with merchant and order specific details and sends response back.

Credit/Debit Card

Merchant will take the card details on his/her website and generates the encrypted card data. Post encryption, the merchant is required to pass this data in the transaction packet.

Once correct request is posted to Pine Labs Payment Gateway, the customer will be redirected to the 3D secure page for a password or OTP authentication. Post payment completion, the customer will be redirected back to merchant's return URL to show the transaction/order status.

Net Banking

Merchant will take the bank selection on his/her page. Bank code for the selected bank will be passed in the transaction request.

Once correct request is posted to Pine Labs Payment Gateway, the customer will be redirected to net banking page of the respective bank. Post payment completion, the customer will be redirected back to merchant's return URL to show the transaction/order status.

EMI

Pine Labs helps the merchant to offer no-cost, low-cost EMI on their products by bringing issuing bank and OEMs on the same platform.

We offer two types of EMI program :

  • Bank EMI
  • Brand EMI

Following steps are involved in the seamless integration of the EMI transactions:

  • EMI calculator API
  • Scheme validation API
  • Transaction request
  • IMEI validation ( applicable only for Brand EMI )
EMI calculator API

Merchant is required to integrate this API to show applicable EMI plans for the transaction.

Scheme Validation API

Merchant is required to integrate this API to check the applicability of EMI plans on a customer card.

Transaction Request

Merchant will take the card details on their website and generate the encrypted card data.

Once the encrypted value is generated, the merchant is required to pass encrypted card data along with the scheme parameters in transaction packet.

Once correct request is posted to Pine Labs Payment Gateway, the customer will be redirected to the 3D secure page for a password or OTP authentication. Post payment completion, the customer will be redirected back to merchant's return URL to show the transaction/order status.

IMEI Validation

IMEI validation is a process to ensure that the product belongs to the OEM who is subventing the EMI transaction.

Mobile SDK Integration

Our Mobile SDK libraries let you easily accept mobile payments inside any Android mobile app.

Android

This sections explains payment flow and integration steps for Android apps.

Android SDK Payment Flow

Different steps as mentioned in the flow diagram.

  • Step 1 : On click of make payment/pay now button,order payload is passed to merchant server by the app.
  • Step 2: Order payload is used to generate checksum by Pine Labs server side utility and secret key(merchant key)on your server. Secret key is shared by Pine labs with merchant. Checksum is a signature used by Pine Labs to ensure the integrity of request.
  • Step 3 : Merchant server pass the payload , Dia secret and Dia secret type back to app .Merchant apps pass all the details to Pine Labs android sdk.
  • Step 4 : Pine Labs sdk accepts and forward the payload to Pine Labs payment gateway.
  • Step 5 : Pine labs payment gateway verifies the payload and accept/denied the request. If payload is valid payment options will be displayed.
  • Step 6 : Once the customer fill the payment details and complete the payment, then merchant app is notified via call back.
  • Step 7 : Merchant verifies the transaction status with transaction status API via server to server call.
Flow Diagram

Step-by-step payment flow is described in below diagram :

flow-diagram

SDK Integration

Step 1 SDK Installation and Setup

Install Pine Labs android SDK using android studio and IntelliJ. To add the SDK to your app, add the following dependency in your build.gradle :

dependencies {
  implementation project(':PineLabsSDK')
} 

Add the following code to your AndroidManifest.xml to get static permission

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
Step 2 Initialization

Object Service : To initialize the Pine Labs SDK ,create the service object

PinePGPaymentManager service=new PinePGPaymentManager();

Object order : Stores all order related information which are required to be passed by you to Pine Labs. Order object is created by following code snippet

Map orderParams=new HashMap<>();
orderParams.put("ppc_UniqueMerchantTxnID" ,"Order ID 123");
orderParams.put("ppc_MerchantID" ,"34133");
orderParams.put("ppc_Amount" ,"12345");
orderParams.put("ppc_MerchantAccessCode"  ,"58ad283b-7c93-4f19-b072-b17e8ecfb20e");
orderParams.put("ppc_NavigationMode"  ,"2");
orderParams.put("ppc_TransactionType"  ,"1");
orderParams.put("ppc_LPC_SEQ"  ,"1");
orderParams.put("ppc_Product_Code"  ,"40");
orderParams.put("ppc_PayModeOnLandingPage" ,"1,3,4,7"");
orderParams.put("ppc_CustomerEmail"  ,"test@pinelabs.com");
orderParams.put("ppc_CustomerMobile" ,"9876543210");
orderParams.put("ppc_CustomerId"  ,"123");
orderParams.put("ppc_CustomerAddress1" ,"Noida B block");
orderParams.put("ppc_CustomerAddressPIN"  ,"201301");
orderParams.put("ppc_DIA_SECRET" ,"w2QDRMgp1234567JEAPCIOmNgQvsi+BhpqijfM9KvFfRiPmGSt3Ddzw+oTaGCLneJwxFFq5mqTMwJXdQE2EzK4px2xruDqKZjHupz9yXev4=");
orderParams.put("ppc_DIA_SECRET_TYPE"  ,"SHA256");

Parameter details can be found in Purchase request section 6.3.1.3 in Pine Labs payment gateway integration guide.pdf

Step 3 Initiate Payment
service.startPayment(orderParams,context,iThemeIdVal,isHeaderTobeShow,isProductionRequest, new IPinePGResponseCallback(){  
@Override
public void internetNotAvailable(int code, String message) {}

@Override
public void onErrorOccured(int code, String message) { }

@Override
public void onTransactionResponse() {}

@Override
public void onCancelTxn(int code, String message) {}

@Override
public void onPressedBackButton(int code, String message) {}
});

Parameters used in start Payment in order are

  • context : context of your Activity is where this method is called.
  • iThemeIdVal: A Integer variable(possible value 0,1,2) to apply theme on Pine labs SDK.
  • isHeaderTobeShow : A Boolean variable (true/false) to hide or show header bar.
  • isProductionRequest : A boolean variable (true/false) to determine whether request is for production environment.
  • IPinePGResponseCallback : IPinePGResponseCallback instance to send call back messages back to merchant android app.
Step 4 Handling call back from Pine Labs SDK

You need to implement call back methods to handle payment response. This will provide the payment status and reason for transaction failures. Based on the reasons for failures, handling can be built at your end. Transaction call backs can be listened via overriding methods of IPinePGResponseCallback.

onTransactionResponse method is called when transaction is complete. Transaction can be fail or success.

internetNotAvailable method is called when internet is not available.

onErrorOccured method is called when SDK is unable to load the payment a page.

onPressedBackButton method is called when user press the back button

onCancelTxn method is called when user cancels the transaction.

Transaction Verification

It is the Rest API used to get the transaction status of the transaction. Merchant needs to call this api after receiving callback of transation.

Parameter details can be found in dependent transaction request section 6.4 in Pine Labs payment gateway integration guide.pdf

Miscellaneous Features

Pay via Link

Merchant asks for customer mobile/email and initiates a transaction. Customer gets a short payment gateway URL via SMS/email on the mobile/email provided to merchant.

Customer clicks on the link and payment gateway page opens. Customer opts for one of the many payment options listed out of credit card / debit card / Netbanking etc.

Customer enters card data and after successful submission, payment status is displayed to customer.

Merchant also gets confirmation about payment along with transaction details.

Brand EMI Calculator

Merchant website can integrate this API to show the latest EMI/Offers applicable on products.

Requesting a test setup

Merchant will need this setup to test the integration with Pine Labs Payment Gateway. Test setup works similar to live environment, however funds transfer between accounts will not take place. To request for test setup or any query email at developer.support@pinelabs.com

Purchase/Sale Request

Overview

It is a Http form post request where merchant will redirect user to Pine Labs payment gateway page along with request parameters.

Request API & URL

API URL Calling mode
Pre-Authorization, Purchase https://uat.pinepg.in/PinePGRedirect Browser redirect/form post

Authentication of Request

Each request is authenticated based on the following :-

Merchant access code, parameter name ppc_MerchantAccessCode. Received value of this parameter will be validated at Pine Labs payment gateway.

Hash of request parameters using Secret key (provided to merchant during merchant registration). Please refer to HashGeneration section for hash generation algorithm.

Parameters for passing hash and hash type are:

  • ppc_DIA_SECRET
  • ppc_DIA_SECRET_TYPE

Merchant must create the ppc_DIA_SECRET using Secret key, ppc_DIA_SECRET_TYPE and request parameters list.

Request parameters Key-Value pair Table

Contains a collection of key-value pairs of all parameters which are required to be sent in sale request

Key Value Details
ppc_MerchantID (required) Integer You can find it in your (merchant) registration data. It is the merchant Id issued by Pine Labs
ppc_Amount (required) Long It is the amount for which payment transaction is required. Greater than zero, in the least currency denominator (e.g. for INR amount is in Paise )
ppc_DIA_SECRET_TYPE (required) String Use SHA256 or MD5 as its Value
ppc_DIA_SECRET (required) String Hash of request parameters. Please refer to HashGeneration section for hash generation algorithm.
ppc_MerchantAccessCode (required) String You can find it in your (merchant) Registration data
ppc_MerchantReturnURL (required) String Browser call back URL. This URL will be used by Pine Labs payment gateway to post and redirect Sale/Pre Auth transaction response.
ppc_NavigationMode (required) Integer Integration mode
2 for Redirect
7 for Seamless
ppc_UniqueMerchantTxnID (required) String
Max Length 99
It is the transaction Id generated at merchant side, for merchant transaction tracking. It is required only for PreAuth and Purchase transactions.
ppc_TransactionType (required) Integer Use-
1 for Purchase,
8 for PreAuth,
3 for Inquiry,
9 for Capture,
10 for Refund
ppc_PayModeOnLandingPage (required) String It will contain csv of valid payment mode Ids.
ppc_CurrencyCode (required) String It is the currency code which is required for handling the amount provided. Use 356 for Indian rupees.
ppc_Product_Code (optional) String It is merchant product code. It is required for brand EMI transaction.
ppc_PayCredentials (optional) String Encrypted card data is send in this attribute.
Applicable only for seamless mode.
ppc_KeyID (optional) Integer Key Id used to encrypt card data.
Applicable only for seamless mode
ppc_TenureID (optional) Integer Tenure ID applicable for seamless EMI transaction
ppc_Scheme (optional) Json
string
Scheme selected by user.
Applicable only in seamless EMI mode
ppc_CustomerId (optional) String.
Max
Length can be
49
In case of Saved Card/Express Checkout, this is used for getting saved cards.
ppc_CustomerEmail (optional) String Email address of customer.
ppc_CustomerMobile (optional) String Mobile number of customer.
ppc_CustomerAddress1 (optional) String Address1 of customer
ppc_CustomerAddress2 (optional) String Address2 of customer
ppc_CustomerAddress3 (optional) String Address3 of customer
ppc_CustomerCity (optional) String City of customer
ppc_CustomerState (optional) String State of customer address
ppc_CustomerCountry (optional) String Country of customer address

ppc_PayModeOnLandingPage

Payment modes send in request must be subset of payment modes enabled on merchant.
If this validation fails, transaction will fail.

If this validation succeeds, Pine Labs payment gateway landing page will show only those options of payment that are sent in ppc_PayModeOnLandingPage

ppc_CustomerId

If incoming request from merchant includes ppc_CustomerId, and payment modes to be rendered are credit/debit card or EMI; Pine Labs payment gateway will check for saved cards. Key for this search will be customer id and merchant id. If saved cards are found, all the saved cards will be shown. User can select any saved card, enter CVV/4DBC and do transactions.

In case of EMI, if customer is having any saved card against selected issuer, saved cards will be shown after EMI table and user can do transaction by entering CVV/4DBC only.

ppc_MerchantReturnURL

This URL will be used by Pine Labs payment gateway to post transaction response. It is mandatory for purchase and preauth transaction types. Also, Pine Labs payment gateway should be having access to this URL. This might need whitelisting of Pine Labs payment gateway URL at merchant set up.

Please note that ppc_MerchantReturnURL sent in transaction request has to be same as the one provided during merchant registration. Multiple return urls can be configured in the system.

If ppc_MerchantReturnURL sent in transaction request and merchant return URL configured for merchant are different, transaction will be rejected.

Response parameters Key-Value pair Table

Key Value Details
ppc_MerchantID Integer In response you can see the merchant id which you have sent as one of the parameter in Pine Labs payment gateway API request parameters.
ppc_MerchantAccessCode String In response you can find the merchant access code which you have sent as one of the parameter.
ppc_UniqueMerchantTxnID String. Max length 99 In response you can find the merchant unique transaction Id which you have sent as one of the parameter.
ppc_PinePGTxnStatus Integer Transaction status
ppc_TransactionCompletion DateTime DateTime The date-time of the transaction completion at Pine Labs payment gateway server.
ppc_Amount Long It is the amount for which payment transaction is being done.
ppc_TxnResponseCode Integer Represent the response of the API request and response code is returned based on the transaction result.
ppc_TxnResponseMessage String Transaction response
ppc_AcquirerName String Acquirer Bank
ppc_PinePGTransactionID Long Unique transaction id generated by Pine Labs
ppc_PaymentMode Integer Payment mode chosen at landing page.
ppc_DIA_SECRET String Hash of response parameters. Please refer to HashGeneration section. Pine Labs payment gateway creates the hash of the response parameters and sends this information in response in tag ppc_DIA_SECRET.
Merchant should use this hash value returned in response to match with new secret generated at its side using other response Parameters. If these two secrets do not match then data is not authentic.
ppc_DIA_SECRET_TYPE String ‘SHA256’ or ‘MD5’ and will be the same which is passed in ppc_DIA_SECRET_TYPE parameter of request
ppc_Is_BankEMITransaction Bool Flag to indicate Bank EMI transaction
ppc_Is_BrandEMITransaction Bool Flag to indicate Brand EMI transaction
ppc_EMITenureMonth Integer Tenure month of EMI transaction
ppc_EMIPrincipalAmount Long Principal EMI amount in Paise
ppc_EMIAmountPayableEachMonth Long Monthly Installment
ppc_EMIInterestRatePercent Integer Interest rate charged by bank multiplied by 10000
ppc_EMICashBackType Integer Its value will be 0 or 1
0 - Pre cash back
1 - Post cash back
ppc_EMITotalDiscCashBackAmt Long Total discount or cashback amount applicable in EMI transaction in paise
ppc_EMITotalDiscCashBackPercent Integer Total discount or cashback percent applicable in EMI transaction multiplied by 10000
ppc_EMIMerchantDiscCashBackPercent Integer Merchant discount or cashback percent applicable in EMI tranasction multiplied by 10000
ppc_EMIMerchantCashBackFixedAmt Long Merchant fixed discount or cashback amount applicable in EMI transaction in paise
ppc_EMIIssuerDiscCashBackPercent Integer Issuer discount or cashback percent applicable in EMI transaction multiplied by 10000
ppc_EMIIssuerDiscCashBackFixedAmt Long Issuer fixed discount or cashback amount applicable in EMI transaction in paise

Dependent Transaction

Web Service: REST Based API

Request parameters are a collection of key-value pairs of all properties which are required to be sent to Pine Labs payment gateway API.

Response returned is in JSON and contains a collection of key-value pairs.

Request API & URL

Hosting API URL Calling mode
TEST Inquiry, Capture, Refund https://uat.pinepg.in/api/PG HTTP post method(content-type will be x-www-form-urlencoded)
PRODUCTION Inquiry, Capture, Refund https://pinepg.in/api/PG HTTP post method(content-type will be x-www-form-urlencoded)

Authentication of API Calls

Each request is authenticated based on the following: -

Merchant access code, parameter name ppc_MerchantAccessCode. Merchant Access code received will be validated at Pine Labs payment gateway.

Hash of request parameters using Secret key (provided to merchant during merchant registration). Please refer to HashGeneration section for hash generation algorithm. Parameters for passing hash and hash type are:

  • ppc_DIA_SECRET
  • ppc_DIA_SECRET_TYPE

Merchant must create the ppc_DIA_SECRET using Secret key, ppc_DIA_SECRET_TYPE and request parameters list.

Request Parameters Key-Value Pair Table

Contains a collection of key value pairs of all parameters which are required to be sent to Pine Labs payment gateway API.

KEY VALUE DETAILS
ppc_MerchantID (required) Integer Shared by Pine Labs on merchant registration.
ppc_Amount (required)(optional for inquiry) Long It is the amount for which payment transaction is required. Greater than zero, in the least currency denominator ( e.g. for INR amount is in Paise )
ppc_DIA_SECRET_TYPE (required) String Values: 'SHA256' or 'MD5'
ppc_DIA_SECRET (required) String Hash of response parameters. Please refer to HashGeneration section. Pine Labs payment gateway creates the hash of the response parameters and sends this information in response in tag
ppc_DIA_SECRET. Merchant should use this hash value returned in response to match with new secret generated at its side using other response parameters. If the two secrets do not match then data is not authentic.
ppc_UniqueMerchantTxnID (required for inquiry) String Merchant transaction id
ppc_MerchantAccessCode (required) String Shared by Pine Labs on merchant registration.
ppc_PinePGTransactionID (required)(optional for inquiry) Long This is the unique transaction id generated by Pine Labs against the transaction id of merchant for 'PreAuth' or 'Purchase' transaction. This is sent to the merchant in response of transaction. This value is used as input parameter for dependent transactions like 'Capture', 'Refund', 'Inquiry'.
ppc_CurrencyCode (required)(optional for inquiry) Integer Use 356 for INR
ppc_TransactionType (required) Integer 3 for 'Inquiry',
9 for 'Capture',
10 for 'Refund'

Response Parameters Key-Value Pair Table

Contains a collection of key value pairs of all parameters which Pine Labs payment gateway will post back in response.

KEY VALUE DETAILS
ppc_MerchantID Integer MID through which transaction has been initiated.
ppc_MerchantAccessCode String MerchantAccessCode used in API request.
ppc_UniqueMerchantTxnID String In response you can find the merchant unique transaction ID which you have sent as one of the parameter.
ppc_PinePGTxnStatus Integer Please refer Pine PG Transaction Status Table.
ppc_TransactionCompletionDat DateTime The date-time of the
eTime   transaction completion at Pine PG server.
ppc_Amount Long. Greater than zero, in the least currency denominator ( e.g. for INR amount is in Paise ) It is the amount for which Payment transaction is being done.
ppc_TxnResponseCode Integer Represent the response status of the API call made to Pine Labs payment gateway. For the response status of parent transaction refer ppc_ParentTxnResponseCode and ppc_Parent_TxnStatus
ppc_TxnResponseMessage String It is the text corresponding to ppc_TxnResponseCode. Please refer to transaction response code list.
ppc_AcquirerName String Acquirer Name
ppc_PinePGTransactionID Long Pine Labs payment gateway unique transaction ID
ppc_DIA_SECRET String Hash of response parameters
ppc_DIA_SECRET_TYPE String ‘SHA256’ or ‘MD5’ and will be the same which is passed in ppc_DIA_SECRET_TYPE parameter of request
ppc_MerchantReturnURL String Return Url which you have posted in request
ppc_EMITenureMonth Integer Tenure months of Emi transaction
ppc_EMIInterestRatePercent Integer Interest rate charged by bank multiplied by 1000
ppc_EMIProcessingFee Long Processing Fee of EMI in paisa
ppc_EMIPrincipalAmount Long Principal EMI amount in paisa
ppc_EMIAmountPayableEachM onth Long EMI Montly installment
ppc_ProductCode String Merchant product Code in case of Brand EMI transaction.
ppc_ProductDisplayName String Product display name
ppc_Is_BankEMITransaction Bool Flag to indicate bank EMI Transaction
ppc_Is_BrandEMITransaction Bool Flag to indicate brand EMI Transaction
ppc_CapturedAmount Long Total amount captured
ppc_RefundedAmount Long Total amount refunded
ppc_EMICashBackType Integer Its value will be 0 or 1
  1. Pre cash back
  2. Post cash back
ppc_EMIIssuerDiscCashBackPer cent Integer Issuer discount or cashback percent applicable in EMI transaction multiplied by 10000
ppc_EMIIssuerDiscCashBackFix edAmt Long Issuer fixed discount or cashback amount applicable in EMI transaction in paisa
ppc_EMIMerchantDiscCashBac kPercent Integer Merchant discount or cashback percent applicable in EMI transaction multiplied by 10000
ppc_EMIMerchantCashBackFixedAmt Long Merchant fixed discount or cashback amount applicable in EMI transaction in paisa
ppc_EMITotalDiscCashBackPerc ent Integer Total discount or cashback percent applicable in EMI transaction multiplied by 10000
ppc_EMITotalDiscCashBackPerc entFixedAmt Long Total fixed discount or cashback percent applicable in EMI transaction in paisa
ppc_EMITotalDiscCashBackAmt Long Total discount or cashback amount applicable in EMI transaction in paisa
ppc_EMIAdditionalCashBack String Additional cashback applicable
ppc_EMIAdditionalRewardPoints Integer Additional rewards points
ppc_PaymentMode Integer Payment mode selected for doing the purchase transaction.
ppc_OriginalTxnAmt Long This the transaction amount for which purchase transaction was done.
ppc_Parent_TxnStatus Integer, Status of the Purchase transaction Please refer Pine Labs payment gateway transaction status table. This field should be mapped for the response status of parent purchase transaction for which API call is made.
ppc_ParentTxnResponseCode Integer, Response code of the Purchase transaction Represent the response of the API request and response code is returned based on the transaction result. This field should be mapped for the response status of parent purchase transaction for which API call is made.
ppc_ParentTxnResponseMessa ge String, Response message of purchase transaction It is the text corresponding to ppc_TxnResponseCode. Please refer to response code list
ppc_ProgramType Integer Values: 106 for Brand EMI.
ppc_MaskedCardNumber String Masked value of card used for purchase transaction.
ppc_ISEZEClick Bool Flag to indicate whether the transaction was done through ezeclick or not.

Note:

The status of the purchase transaction for which an inquiry API call is made should be inferred from parameters ppc_Parent_TxnStatus and ppc_ParentTxnResponseCode.

Status Value of ppc_Parent_TxnStatus Value of ppc_ParentTxnResponseCode
Successful parent purchase transaction 4 1

Hash Generation

This Method takes input data dictionary, Secure Secret Key, Hash Type and reference string for Generated Hash by this Method. If this Method fails in processing it returns false. If Method returns true then the calculated Hash string value will be set to the reference variable (strHash variable in the below described method)

Input Parameters:

dictInput:

Input key Value Pair Dictionary has all the input fields except Secure Secret Hash and Hash Type.

strSecretKey:

Secure Secret Key Provided by PinePG strHashType: Hashing Algorithm Type strHash: This Parameter is passed as reference. It will be set as the Generated Hash Value.

Return Parameter:

DataType as bool (true/false), It will be true in case of success else it will be false.

///  
/// This Method is used to Generate Hash.  
/// If Method returns true, strHash will contain Generated Hash value. 
///  
///  
/// Input Data Dictionary of Message to be hashed 
///  
///  
/// SecureSecret Provided By PinePG 
///  
///  
/// Hash Generation Algorithm 
///  
/// - Out Param 
/// Generated Hash Value.  
///  
///  
/// If true then Success, else Fail 
///  
private bool GenerateHash(Dictionary dictInput,  string strSecretKey, string strHashType, ref string strHash) 
{ 
bool bReturn = false; 
try {  
    if ((dictInput == null ) || (dictInput.Count == 0 ) || (string.IsNullOrEmpty(strSecretKey)) || (string.IsNullOrEmpty(strHashType))) 
    { 
        return bReturn; 
    } 
 
    SortedList sortdLstRequestFields = new SortedList(); 
   
    foreach (KeyValuePair keyValPair in dictInput) 
    {               
            sortdLstRequestFields.Add(keyValPair.Key, keyValPair.Value); 
    } 
    //Convert Secret Key to required format 
    byte[] convertedHashKey = new byte[strSecretKey.Length / 2];     
	for (int i = 0; i < strSecretKey.Length / 2; i++) 
    { 
        convertedHashKey[i] = (byte)Int32.Parse(strSecretKey.Substring(i * 2, 2), System.Globalization.NumberStyles.HexNumber);     
	} 
 
    // Build string from collection. 
    StringBuilder sbMessage = new StringBuilder();     
	foreach (KeyValuePair kvp in sortdLstRequestFields) 
    { 
            sbMessage.Append(kvp.Key + "=" + kvp.Value + "&"); 
    } 
    sbMessage.Remove(sbMessage.Length - 1, 1); 
 
    strHash = "";             
    //generate hash 
    if (strHashType.ToUpper().Equals("SHA256")) 
    { 
        using (HMACSHA256 hasherSHA256 = new HMACSHA256(convertedHashKey)) 
        { 
            byte[] hashValue = hasherSHA256.ComputeHash(Encoding.UTF8.GetBytes(sbMessage.ToString()));             
			foreach (byte b in hashValue) 
            { 
                strHash += b.ToString("X2"); 
            }         
		}        
		bReturn = true; 
     } 
    else if (strHashType.ToUpper().Equals("MD5")) 
    {        
        using (HMACMD5 hasher = new HMACMD5(convertedHashKey)) 
        { 
            byte[] hashValue = hasher.ComputeHash(Encoding.UTF8.GetBytes(sbMessage.ToString()));             
			foreach (byte b in hashValue) 
            { 
                strHash += b.ToString("X2"); 
            }         
		} 
        bReturn = true; 
    }  
    if (string.IsNullOrEmpty(strHash)) 
    { 
        bReturn =  false; 
    }          
 } 
catch (Exception ex) 
{     bReturn = false; 
} 
return bReturn; 
} 

EMI Calculator

Overview

EMI Calculator as the name suggests provides a platform /API information exchange to display various EMI offers details. This section describes the elaborate details of an interface which will provide the information for EMI Offers.

The Merchant website can integrate the interface to show the customer, latest Emi/Offers applicable on products.

API Details

The request for accessing interface should use HTTP POST and the response will be JSON. URL. The following section will elaborate the specification

Request Parameters

Parameter Name Type Description
MERCHANT_ID (required) Integer You can find it in your (merchant) Registration data
MERCHANT_ACCESS_CODE (required) String You can find it in your (merchant) Registration data
PRODUCT_CODE (required) String Merchant product code which has been mapped with Pine Labs product code
AMOUNT (required) Long Amount is in paise

Response Parameters

The request for accessing interface should use HTTP POST and the response will be JSON. URL. The following section will elaborate the specification

Parameter Name Type Description
RESPONSE_CODE Integer Response code of api. List of response code defined in Glossary.
RESPONSE_MESSAGE String Response Message
ISSUER List of user defined class example List Defines list of card Issuing bank and their emi parameters

Structure of ISSUERS_EMI_DETAILS

Parameter Name Type Description
ISSUER_NAME (optional) String Card issuing bank
LIST_EMI_TENURE (optional) List of user defined class example List Defines emi parameters for issuing bank

Structure of TenureDetails

Parameter Name Type Description
TENURE_IN_MONTHS (optional) Integer Tenure of Loan
MONTHLY_INSTALLMENT (optional) Double Monthly emi in INR
BANK_INTEREST_RATE (optional) Double Bank Interest Rate
INTEREST_PAY_TO_BANK (optional) Double Amount(In INR) payable to bank as interest
TOTAL_OFFERED_DISCOUNT_PERCENTAGE (optional) Double Discount percentage
TOTAL_OFFERED_DISCOUNT (optional) Double Discount in INR
TOTAL_OFFERED_CASHBACK_PERCENTAGE (optional) Double Cash back percentage
TOTAL_OFFERED_CASHBACK (optional) Double Cash back in INR
TOTAL_DISCOUNTED_AMOUNT (optional) Double EMI is calculated on this amount if discount is applicable. Product Amount- Total offered discount
ADDITIONAL_CASHBACK (optional) String Additional cash back available on product
EMI_CALCULATION_MESSAGE (optional) String Emi calculation message. e.g. EMI is calculated on discounted amount

Request and Response Data

Sample Request

MERCHANT_ID=2477&MERCHANT_ACCESS_CODE=c282ff26-b2d6-48f3-88ad-081b8933a5f1&PRODUCT_CODE=emi1&AMOUNT=4000000

Sample Response

{ 
"RESPONSE_CODE":"1", 
"RESPONSE_MESSAGE":"SUCCESS", 
"ISSUER":"{"  ISSUERS_EMI_DETAILS":[ 
 	{ 
"LIST_EMI_TENURE":[ 
{ 
"TENURE_IN_MONTHS":"3", 
"MONTHLY_INSTALLMENT":"12200.54", 
"BANK_INTEREST_RATE":"10.00", 
"INTEREST_PAY_TO_BANK":"601.62", 
"TOTAL_OFFERED_DISCOUNT_PERCENTAGE":"10.00", 
 	"TOTAL_OFFERED_DISCOUNT":"4000.00", 
"EMI_CALCULATION_MESSAGE":"EMI is Calculated On Discounted 
 	Amount", "TOTAL_DISCOUNTED_AMOUNT":"36000.00" 
}, 
{ 
"TENURE_IN_MONTHS":"1", 
"MONTHLY_INSTALLMENT":"0.00", 
 	"BANK_INTEREST_RATE":"0.00", 
"INTEREST_PAY_TO_BANK":"0.00", 
"TOTAL_OFFERED_DISCOUNT_PERCENTAGE":"10.00", 
 	"TOTAL_OFFERED_DISCOUNT":"4000.00", 
"EMI_CALCULATION_ MESSAGE ":"No EMI Only Discount Is Available", 
 	"TOTAL_DISCOUNTED_AMOUNT":"36000.00" 
} 
], 
"ISSUER_NAME":"HDFC" 
}, 
{ 
"LIST_EMI_TENURE":[ 
{ 
 	"TENURE_IN_MONTHS":"3", 
"MONTHLY_INSTALLMENT":"12430.56", 
"BANK_INTEREST_RATE":"8.00", 
"INTEREST_PAY_TO_BANK":"491.68", 
"TOTAL_OFFERED_DISCOUNT_PERCENTAGE":"8.00", 
"TOTAL_OFFERED_DISCOUNT":"3200.00", 
"EMI_CALCULATION_ MESSAGE ":"EMI is Calculated On Discounted Amount",
"TOTAL_DISCOUNTED_AMOUNT":"36800.00" 
}, 
{ 
"TENURE_IN_MONTHS":"1", 
"MONTHLY_INSTALLMENT":"0.00", 
"BANK_INTEREST_RATE":"0.00", 
"INTEREST_PAY_TO_BANK":"0.00", 
"TOTAL_OFFERED_DISCOUNT_PERCENTAGE":"10.00", 
 	"TOTAL_OFFERED_DISCOUNT":"4000.00", 
"EMI_CALCULATION_ MESSAGE ":"No EMI Only Discount Is Available", 
 	"TOTAL_DISCOUNTED_AMOUNT":"36000.00" 
} 
], 
"ISSUER_NAME":"YES" 
 	}, 
{ 
"LIST_EMI_TENURE":[ 
{ 
"TENURE_IN_MONTHS":"3", 
"MONTHLY_INSTALLMENT":"12200.54", 
"BANK_INTEREST_RATE":"10.00", 
"INTEREST_PAY_TO_BANK":"601.62", 
"TOTAL_OFFERED_DISCOUNT_PERCENTAGE":"10.00", 
 	"TOTAL_OFFERED_DISCOUNT":"4000.00", 
"EMI_CALCULATION_ MESSAGE ":"EMI is Calculated On Discounted 
 	Amount", "TOTAL_DISCOUNTED_AMOUNT":"36000.00" 
}, 
{ 
 	"TENURE_IN_MONTHS":"1", 
"MONTHLY_INSTALLMENT":"0.00", 
"BANK_INTEREST_RATE":"0.00", 
"INTEREST_PAY_TO_BANK":"0.00", 
"TOTAL_OFFERED_DISCOUNT_PERCENTAGE":"10.00", 
 	"TOTAL_OFFERED_DISCOUNT":"4000.00", 
"EMI_CALCULATION_ MESSAGE ":"No EMI Only Discount Is Available", 
 	"TOTAL_DISCOUNTED_AMOUNT":"36000.00" 
} 
], 
"ISSUER_NAME":"RBL Bank" 
} 
] 
}" 
}  
   

Response Codes

The following section describes the set of Response codes and the corresponding response messages.

Response Code Response Message
1 SUCCESS
-1 FAILURE
-2
MERCHANT_ACCESS_CODE CAN NOT BE NULL
OR BLANK
-4 AMOUNT CAN NOT BE NULL OR BLANK
-5 PRODUCT_CODE CAN NOT BE NULL OR BLANK
-14 MERCHANT_ID CAN NOT BE NULL OR BLANK
-6
INVALID MERCHANT_ID OR MERCHANT_ACCESS_CODE
-7 INVALID PRODUCT_CODE
-8 INVALID AMOUNT
-10 INVALID MERCHANT_ID
-11
EITHER PRODUCT_CODE NOT PRESENT OR MAPPING NOT PRESENT WITH MERCHANT
-13
NO EMI FACILITY IS AVAILABLE ON THIS
PRODUCT
-14 MERCHANT_ID CAN NOT BE NULL OR BLANK

Scheme Validation

Introduction

Seamless EMI flow allows merchant to display EMI offer and collect card details on its website. This flow enhances customer experience as there will not be multiple redirection.

Request parameter

Key Value type Details
RESPONSE_CODE Numeric Value 1 is Success,-1 is Failure
RESPONSE_MESSAGE Numeric SUCCESS,FAILURE

IMEI Validation

Overview

This section outlines the IMEI validation API and its parameters. Merchant can integrate this API and real time response from the OEM will be shared back.

Request

Request parameters are a collection of key-value pairs of all properties which are re-quired to be sent to Pine PG API.

Response returned is in JSON and it contains a collection of key-value pairs of properties which describes about the request sent and its status returned in this response.

Key Value Details
TEST https://uat.pinepg.in:8059/ api/IMEIValidation HTTP post method("Content-Type: application/x-www-form-urlencoded")
PROD https://pinepg.in:8098/api/IMEIValidation HTTP post method("Content-Type: application/x-www-form-urlencoded")

Request Parameters

Key Value Details
PinePGTransactionId (required) Numeric Pine PG transaction ID share to merchant in transaction response
IMEI (required) String IMEI to be validated
TransactionType Numeric Following are the expected values: 1- Blocking 2-Override 3-Unblocking
IMEIValidationOverride (required) String This is used in case IMEI validation is to be override. Reason is to be shared if TransactionType=2
UserName (required) String Not in use
AccessCode (required) String Not in use


Sample request
PinePGTransactionId=229363&IMEI=334433440000552&TransactionType=1&IMEIValidationOverrideReason=&UserName=&AccessCode=

Response Parameters

Key Value Details
statusCode Numeric Success is when statuscode and errorcode is received with value 0 else failure
errorMessage String Error description
errorCode String Success is when statuscode and errorcode is received with value 0 else failure
printData Not for merchant use

Sample response data:

{ 
"statusCode": -1, 
"errorMessage": "Transaction not eligible for validation", 
"errorCode": -6, 
 
"printData": "false;false;true;1;------------------------|false;false;true;2;IMEI VALIDATION 
ERROR|false;false;true;3;ERROR|false;false;true;4;Transaction ID is|false;false;true;5;already using an IMEI|false;false;true;6;------------------------ 
 
|false;false;true;7;javed_08122017|false;false;true;8;fghyughy|false;false;true;9;dqsdasda|false;fa lse;true;10;Delhi|false;false;true;11;Delhi|false;false;false;12; |false;false;false;13;--------------------- 
 
---|false;false;false;14; |false;false;false;15;DATE: 2018-04- 	 	 
05|false;false;false;16;TIME: 03:08:51|false;false;false;17;MID: TEST9820454239|false;fals e;false;18; |false;false;false;19; 	----------SALE---------- 	|false;false;false;20;  	 
|false;false;false;21;Card:  345678*****0007|false;false;false;22;CARD 
TYPE: AMEX|false;false;false;23;TXN 	 	 	 
 }  
 

Glossary

Response Codes for Sale and Dependent
PINE_PG_TXN_RESPONSE_ CODE PINE_PG_RESPONSE_MESSAGE
1 SUCCESS
-1 FAILURE
-5 EXPIRED CARD
-6 INSUFFICIENT FUND
-7 CORRPUT INPUT DATA
-8 UNSUPPORTED TXN TYPE
-9 CARD VERIFICATION FAILURE
-10 TXN CANCELLED
-11 TXN DEFERRED
-12 TXN DECLINED
-13 CARD SECURITY CODE VERIFICATION FAILED
-14 DUPLICATE TXN
-15 TXN SUBMITTED
-16 NOT ENROLLED FOR 3DS
-17 TXN PENDING
-18 RETRY LIMIT EXCEEDED
-19 DUPLICATE BATCH
-20 ADDRESS VERIFICATION FAILURE
-21 AUTHENTICATION FAILED
-22 ADDRESS VERIFICATION AND CARD SECURIRY CODE VERIFICATION FAILURE
-23 PAYMENT PLAN NOT SUPPORTED
-24 WAITING FOR ACQUIRER CONFIRMATION
-25 PRE AUTH NOT ENABLED
-26 CAPTURE NOT ENABLED
-27 PURCHASE NOT ENABLED
-28 INQUIRY NOT ENABLED
-29 REFUND NOT ENABLED
-30 PAYMENT MODEL NOT SUPPORTED
-31 SECURE HASH NOT RETURNED FROM ACQUIRER
-32 SECURE HASH RETURNED FROM ACQUIRER NOT MATCH
-33 SECURE HASH NOT RETURNED FROM MERCHANT
-34 SECURE HASH RETURNED FROM MERCHANT NOT MATCH


Transaction Status
TXN_STATUS_ID TXN_STATUS_NAME DESCRIPTION
-10 Cancelled When the user cancels the transaction.
-9 Auth Cancelled Authorisation transaction has cancelled due to some reasons e.g.bank session time out, capture transaction failed.
-8 Velocity Check Failed Velocity check failed for EMI transactions
-7 Failure Transaction has failed due to some reasons e.g. bank session time out, insufficient funds. Payer needs to re-initiate the transaction.
-6 Rejected Transaction has been rejected.
1 Initiated Pine Labs payment gateway has not received response from Payment Provider/Bank. For all such transactions, We will retry the transaction, post which the transaction status will be updated to ‘Captured‘ or‘AuthReceived’ or ‘Rejected’.
2 Auth Received Authorization successful.This transaction will be on hold for 24 hours. After risk analysis this transaction will be marked as 'AuthComplete' in Pine Labs payment gateway system.
3 Auth Complete Transaction is now eligible for 'Capture'. It can be 'Auto-Captured' by Pine Labs payment gateway. Merchant can 'Capture' it using merchant console post-delivery confirmation. Transaction which is not captured within predefined auth expiry days will be cancelled.
4 Captured 'Captured' call is successful. Funds will be transferred to merchant account.
5 Cleared Funds have been transferred to Merchant account.
6 Refunded Refund of the transaction is successful.
7 Query Complete Query of the transaction is successful.

References

For API references: Click here

Github link for code samples: Click here

Github link for Purchase and Pre-Auth transaction types: Click here