Sorry, your browser does not support JavaScript! Plural XT Docs - Pine Labs Developer

Plural XT

Introduction                 

Pine Labs' Plural XT is a system that facilitates the integration with a number of online payment gateways. It provides an umbrella type relationship with payment gateways and promises its merchant the intelligent dynamic routing, deeper analytics, unified dashboard, simpler integration process.

In addition to multiple payment gateways integration, Pine Labs' Plural XT offers following features to the merchant.

  1. Support of multiple Payment Aggregators/Payment Gateways
  2. Through Pine Labs' Plural XT, you can integrate with multiple payment aggregators or payment gateways.
  3. Intelligent Routing
  4. Pine Labs' Plural XT offers intelligent dynamic routing of transactions to acquirers. The inbuilt intelligent routing of Pine Labs' Plural XT aims at optimizing the highest success rate at one hand and best commercials at the other. Further, Pine Labs' Plural XT also enables you to write your own priority logic or tweak the existing logic to decide the routing.
  5. Unified Dashboard
  6. When you integrate with multiple gateways, you get transaction and other data at respective payment gateways' dashboards. This multiplicity of dashboards gives a scattered picture of the data. Pine Labs' Plural XT provides you a unified merchant dashboard on which data of all the payment gateways you have configured is available in one place. Further, it also provides a host of useful functionalities such as the configuration of payment gateways, a refund of transactions, removal of the saved card, and deeper analytics.
  7. Card Vault
  8. Pine Labs' Plural XT provides you saved card feature in which your customer can save a card while transacting. The customer does not have to enter the card numbers and expiry date again when she uses it again in the future. Saved cards can be used for all the payment gateways configured by you. You do not have to have separate card vaults for different payment gateways. Further, you do not bear the burden of PCI-DSS L1 compliance which is compulsory to have a card vault.
  9. Simple Integration process
  10. You do not have to go through a long process of integration with the payment gateways. You only have to do a one-time activity of integration with the Pine Labs' Plural XT. Payment gateways can be integrated through the Pine Labs' Plural XT's merchant dashboard only by configuring the credentials you receive from the payment gateway you want to integrate.

List of Acquirers

Aggregators Bank PG Wallets Net Banking UPI
BillDesk ICICI PayZapp BillDesk HDFC
Razorpay HDFC PayU PayU PayU
PayU Axis Razorpay Razorpay Razorpay
PhonePe G-Pay

Create an account

To proceed with Pine Labs' Plural XT, you need to create an account. You can register as a merchant right away from here and explore the dashboard. Our representative will then connect with you to complete the onboarding process. Alternatively, you can also contact us from here.

Once you are onboarded, an API Key will be issued to you. This key is used for authenticating the API requests initiated from your application. You are advised to keep the API Key secret and should not share it with anyone.

API Key can be obtained from the dashboard's settings page as well.

Integration

Order Creation

Order represents the shopping cart in a payment journey. Order plays a central part in the payment flow as the subsequent transactions such as payment, refund, get status are linked to it. For this, an order must be identified uniquely and to do so you can create and assign a random and unique order_id to an order. This order_id can be used for any subsequently linked transactions to the order.

An order comprises of the following details:

  1. Order Identifier - Order Id
  2. Payment details - Amount, Currency and Preferred PG
  3. Customer details - Customer Id, Customer Email, Customer Mobile.
  4. Product details - Product Id
  5. Address - Billing Address and Shipping Address
  6. Other details

More details related to an order creation can be found in API References.

Payment

Once the order is created successfully, an order reference id is returned which the merchant needs to save in his database for future reference of the created order. Along with this, Pine Labs' Plural XT also returns a token in the response.

When order creation response is received then the merchant will need to call second consecutive server to server call which would process the payment to create unique transction id. In this API call merchant need to pass Card/UPI/GPAY/Netbanking transaction related data.

In the response, the response code and response status are sent.

{
"redirect_url": "http://localhost:51462/pinepg/v2/process/payment?token=9KK5R9b3ZKFP304GcKWgFagM7utHs3tzgignoZWEu%2bQ%3d",
    "response_code": 1,
    "response_message": "SUCCESS"
}

Merchant needs to redirect to API of which the URL was shared in Process Payment API. API would call host to process transaction.

EMI Integration

1. Offer Discovery

Offer Discovery is the process through which a merchant can get the details of all the EMI offers available on a product. This is achieved through calling our EMI Calculator API. In the request a merchant needs to send the following information:

  1. Merchant Details
  2. Product Details
  3. Amount

In the response, the following details are sent:

  1. Whether a scheme is valid on the product or not
  2. Subvention cashback discount (both fixed and percentage)
  3. Subvention type
  4. Additional cashback
  5. Bank interest rate
  6. EMI tenures
  7. Installment amount
  8. Load amount
  9. Auth amount
  10. Issuer name

These details enable merchants to curate the payment pages to show the offers available on a product.

2. Scheme Validation

Once the Offer Discovery is done, the merchant needs to call the Scheme Validation API. The role of Scheme Validation API is to confirm the availability of the scheme on the card of the customer. For this, the merchant needs to supply the following details.

  1. Merchant Data
  2. Card data of the customer
  3. EMI details of the offer which customer wants to avail

The response, the response code and response message are returned. Subsequently, the Order creation and Payment processing are done. Additional details are described in API References.

Refund

Refund of the charges for which the transaction has already been done successfully and not refunded previously can be created. Refunds can be initiated either through Refund API or from the merchant dashboard. Further, Refund can be made partially or fully.

API Dashboard
Full Refund YesYes
Partial Refund YesYes

1. Refund through API
In the Refund API request, a merchant needs to pass the unique_merchant_txn_id of the transaction which is intended to be refunded and the amount to be refunded.

2. Refund through Dashboard
From the Merchant Dashboard, a merchant can select an order or a transaction and click on refund. It will show a pop-up window in which the refund amount is to be provided. Alternatively, a merchant can select multiple orders and initiate refund of all the selected orders. In later case, partial refund is allowed. However, if a merchant intends to initiate the refund in bulk, she can download bulk refund csv file and provide the required details. In this way, the partial refund in bulk can be made.

Payment Aggregators(PAs) and Payment Gateways(PGs)

PAs/PGs can be configured by the merchant from the merchant dashboard. A merchant can configure those gateways only which are supported by Pine Labs' Plural XT. The list of these gateways is given below :

  1. ICICI
  2. HDFC
  3. Axis
  4. PayU
  5. Razorpay
  6. BillDesk
  7. PhonePe
  8. Google Pay
  9. Amex*

A merchant first needs to collect the merchant credentials from the PA/PG. Then, the merchant needs to visit the Merchant Dashboard of Pine Labs' Plural XT and go to gateways sections. Thereafter, the merchant selects the gateway which he intends to configure and from which merchant credentials are obtained. Once the gateway is selected by the merchant it will show a form in which gateway related details are to be filled.

*For Amex, please contact the support team.

Dynamic Routing

Success rate is of the utmost importance to merchants. For big merchants even small variation in the success rate results in huge movements in the volume and thus the revenue. Merchants often integrate with multiple gateways to achieve a better success rate and commercials (MDR - Merchant Discount Rate, a rate merchants pay for the transacted volume). However, the optimization of gateways is a tricky task as it involves multiple criteria. Pine Labs' Plural XT's Dynamic Routing engine is built to provide the best success rate from amongst the available gateways to a merchant. This engine takes into account gateways health, patterns of successful transactions on an acquirer, issuers, BIN and payment schemes. Further, Pine Labs' Plural XT also empowers merchants to modify the routing by provide the preference of routing and altering the weightage of an acquirer in the routing. Merchants can execute such functions through the Pine Labs' Plural XT Merchant Dashboard.

Basic Routing

Under the Basic Routing, a merchant can set a preferred gateway and fall back gateways. Fall-back gateways are considered in the case when the preferred gateway is down or cannot be preferred due to some other reasons. Fall back options are provided by the merchant in an order and these are to be considered for routing by Pine Labs' Plural XT in the same order only.

Custom Routing

Pine Labs' Plural XT provides control to the merchant to define and modify the routing logic. This logic can be written in JavaScript using the JavaScript editor on the Dashboard. A sample JavaScript code of the logic is shown below.

	
 var priorties=["HDFC","ICICI"];
 if(order.preferred_gateway=="YES"){
 	priorties=["YES"];
 }else{
 	if(timestamp%10<5){
 		priorties=["AXIS","AMEX"];
 	}else{
 		priorties=["RAZOR_PAY"];
 	}
 }
 priorties=["HDFC","ICICI"];
 if(txn.payment_mode=="CREDIT_DEBIT"){
 	priorties=["YES"];
 }else{
 	if(timestamp%10<5){
 		priorties=["AXIS","AMEX"];
 	}else{
 		priorties=["RAZOR_PAY"];
 	}
 }
 var priorties=["HDFC","ICICI"];
 if(order.preferred_gateway=="HDFC"){
 	priorties=["HDFC"];
 }else if(payment.card_bin=="401200"){
 	priorties=["PayU"];
 }else{
 	if(timestamp%10<5){
 		priorties=["AXIS","AMEX"];
 	}else{
 		priorties=["RAZOR_PAY","BILLDESK"];
 	}
 }

Merchants can write logic to route transactions based on number of criteria such as:

1. Platform-based Routing

If a merchant intends to route transaction originating from website to payment gateways and those originating from mobile to the other payment gateways, he can write the routing logic accordingly. Sample code is shown below:

var priorties=["HDFC","ICICI"];
if(order.preferred_gateway=="HDFC"){
	priorties=["HDFC"];
}else if(payment.card_bin=="401200"){
	priorties=["PayU"];
}else{
	if(timestamp%10<5){
		priorties=["AXIS","AMEX"];
	}else{
		priorties=["RAZOR_PAY","BILLDESK"];
	}
}

2. Split Volume Routing

Merchants can customize the routing based on the division of transactions amongst the gateways configured for the merchant. For instance, if a merchant wishes to route 50% volume to PG1, 30% volume to PG2 and 20% volume to PG3, he can do so. Sample code is shown below:

var priorties=["HDFC","ICICI"];
if(order.preferred_gateway=="HDFC"){
	priorties=["HDFC"];
}else if(payment.card_bin=="401200"){
	priorties=["PayU"];
}else{
	if(timestamp%10<5){
		priorties=["AXIS","AMEX"];
	}else{
		priorties=["RAZOR_PAY","BILLDESK"];
	}
}

3. Issuer-based Routing

Routing logic can be customized in a way which can route transactions to PGs based on the Issuers.

var priorties=["HDFC","ICICI"];
if(order.preferred_gateway=="HDFC"){
	priorties=["HDFC"];
}else if(payment.card_bin=="401200"){
	priorties=["PayU"];
}else{
	if(timestamp%10<5){
		priorties=["AXIS","AMEX"];
	}else{
		priorties=["RAZOR_PAY","BILLDESK"];
	}
}

4. Payment Scheme based Routing

Merchants can write routing logic in which the routing can be done based on the payment schemes. Sample code is shown below:

var priorties=["HDFC","ICICI"];
if(order.preferred_gateway=="HDFC"){
	priorties=["HDFC"];
}else if(payment.card_bin=="401200"){
	priorties=["PayU"];
}else{
	if(timestamp%10<5){
		priorties=["AXIS","AMEX"];
	}else{
		priorties=["RAZOR_PAY","BILLDESK"];
	}
}

Special Routing

Special routing enables merchants to play an important role in the routing engine by controlling the routing by changing the weightage of preference of PGs. This can be done through the following means:

1. Card BIN based routing

BIN or Bank Identification Number is the initial set of six numbers which is used for identification of the bank which issued the payment card. Merchant can configure the route score for the combination of BIN and PGs. This score is used for the ranking of the routing transactions. Score can vary between 0 and 2. Default score of routing is 1. Routing preference increases as the score goes up.

2. Issuer based routing

Like the case of BIN, score can be given to the Issuer-PG combinations as well.

3. Payment Scheme routing

Like the above two cases, the scores can be defined for payment scheme - gateway combinations.