Server to Server Integration

Overview

This document outlines server-to-server integration, which entails establishing a direct connection between your server and the Pine Labs payment application using APIs. It enables seamless communication and data exchange between the two systems, facilitating automated payment processing and transaction management without any intermediate applications or SDKs.

Transaction Lifecycle in Integrated Flow

It is important to understand the lifecycle of a PoS transaction when working in an integrated manner with Pine Labs Billing System. The diagram given below demonstrates the complete lifecycle.

Transaction Lifecycle

A transaction can have the following stages from a third-party perspective:

  1. Paid
    In this stage, the server has successfully received the payment against the order and a payment charge slip has been generated.
  2. Void
    After a transaction has been successfully paid for, it can be voided by the user. In this case, any associated card transaction will be marked as void and a void charge slip will be generated. Support for “Transaction Void” is generally removed to avoid any fraud being done by the cashier.
  3. Reversed
    Due to mobile network or PoS hardware issues, it is possible for a transaction to get reversed after it has been paid. The Transaction reversals are automatic as opposed to transaction voids which are cashier driven. When the cashier performs the next action on the PoS (such as a next transaction or batch settlement), the server detects the transaction reversal and reverses any associated card transactions. A transaction reversal message briefly pops up on the PoS device, but no charge slips are generated for the transaction reversal.

Integration Points with Pine Labs server

Third Party server needs to host following services for Pine Labs to consume:

  1. Fetch Data against an entered Unique Number on the EDC This service is invoked by Pine Labs servers to fetch information from a third-party server. In this service Pine Labs server will pass inputs entered by the user on EDC machine and fetch the bill data for which payment is to be received. After successfully fetching this information, transaction would be initiated.
  2. Update Payment Details This service is used by Pine Labs servers to post payment information to a third-party server. In this service, PL will pass the payment information along with payment mode, payment amount etc.
  3. Reverse Payment Details
    This service is used by Pine Labs servers to update the third-party server about any payment reversals. Payment reversals will arise when
    a)  User voids Transaction
    b)  Transaction gets reversed.

Fetch Data Service

This service is invoked by Pine Labs servers to fetch bill information from the third-party server. After entering the input on the POS device, the Pine Labs server will send a request to the third-party server. The response, which is expected, will contain the due amount and other information to be printed on the charge slip.

Sample Request


HTTP Method: POST
Request Headers:
          
        X-PL-PoSId: 3453453
      X-TP-ApiKey: apikey
      X-req-hash: ITTOC7fJr6bJcb7HVJUwVa1zss6GfOyfuuNHENu3GlY=
      Content-Type: application/x-www-form-urlencoded
X-PL-PoSId is the unique identifier for EDC machine in Pine Labs ecosystem. It can be used for whitelisting/blacklisting of EDC terminals.
X-TP-ApiKey is the secret API key issued by third-party to Pine Labs. It is recommended that Third Party whitelists the IPs of PL servers in production environment.
X-req-hash is SHA256 digest of the request body. See section HMAC-SHA256 Message Digest Calculation. for exact calculation methodology.

Endpoint:
          
        https://{tpserverhost}/fetchBillInfo

Request Body:
          
        paramName1=paramValue1&paramName2=paramValue2
As indicated by the content type header in Request Headers section, request body will be “x-www-form-urlencoded” encoded.
Names of the parameter and its values can be decided at the integration time and will be fixed across environments i.e. same across test, uat and production. The max length of the parameter value is restricted to 19 characters (alphanumeric).

There can be a maximum of 3 input parameters.

Sample Response:


HTTP Method: POST
Request Headers:
            
          {
        “status” : 0,
        “reason” : “NA”,
        “billAmount” : 10075,
        “billIdentifier” : “N23534654564”,
        “chargeslipInfo” : {
          “CustomerName”: “Vijay Singh”,
          “CircleName”: “Pune Municipal”
        },
        “allowedPaymentModes”: [1,2,10]
        }


WHERE

Sr.No Fields Description Values
1 status 0 denotes success, other values denote failure. Format: Integer Length: Numeric (2) Format: Integer
Length: Numeric (2)
2 reason Reason for the response. Can be null for status 0. Must be populated where status is not 0. It is displayed to the EDC user. Format: String Length: Alphanumeric(50) Format: String
Length: Alphanumeric(50)
3 billAmount Amount is paise. Max value is 9_99_99_999_99 Format: Long Length: Numeric(10) Format: Long
Length: Numeric(10)
4 billIdentifier Unique identifier of the bill on the Third Party Server Format: String Length: Alphanumeric(20) Format: String
Length: Alphanumeric(20)
5 chargeslipInfo It is the map of the values that need to be printed on the charge slip. The values are printed “as is” with no change in formatting. All values should be string. Format: JSON Object with string values only. Format: JSON Object with string values only.
6 allowedPaymentModes It is an array of payment modes allowed for this bill. Values other than those enabled at integration time are ignored. A null or empty array mean all payment modes are allowed. See section Billing Server Payment Modes for possible values of payment modes. Format: JSON Array of Integers Format: JSON Array of Integers

Update Payment Details

After payment has been completed against the bill, Pine Labs will invoke this API hosted by the third party to update them about the payment receipt against the bill.

Sample Request


HTTP Method: POST
Request Headers:
            
          X-PL-PoSId: 3453453
        X-TP-ApiKey: apikey
        X-req-hash: ITTOC7fJr6bJcb7HVJUwVa1zss6GfOyfuuNHENu3GlY=
        Content-Type: application/json
X-PL-PoSId is the unique identifier for EDC machine in Pine Labs ecosystem. It can be used for whitelisting/blacklisting of EDC terminals.
X-TP-ApiKey is the secret API key issued by Third Party to Pine Labs. It is recommended that Third Party whitelists the IPs of PL servers in production environment.
X-req-hash is HMAC-SHA256 digest of the request body. See section HMAC-SHA256 Message Digest Calculation for exact calculation methodology.

Endpoint:
                
              https://{tpserverhost}/updatePaymentInfo
Where
tpserverhost is the host/port info of the third party server.

Request Body:
                
              {
  “billIdentifier” : “23432423”, 
  “plTransactionId” : 32343,
  “paymentMode” : 2, 
  “transactionTime” : "2018-08-07T07:16:04.860+0530",
  “transactionAmount” : 2452353,
  “cashModeInfo” : {
  “cashAmount” : 345345
  },
  “cardModeInfo” : {
  “cardAmount” : 2342,
  “cardApprovalCode” : “43334”, 
  “cardMaskedNumber” : “343433XXXXXXX5678”,
  “cardTid” : “234242”,
  “cardAcquirer”:”SBI”,
  “cardAcquirerMid” : “252353453”,
  “cardHolderName” : “SH RAM”
  },
  “chequeModeInfo” : {
  “chequeAmount” :234324,
  “chequeNumber” : 345543,
  “chequeMicr” : 242353423,
  “chequeDate” : “07042017”,
  “chequeBank” : 2
  },
  “qrBasedModeInfo” : {
  “qrAmount”:24234,
  “qrTranactionId” : “3534534534”,
  “qrHost” : “HDFC BHARAT QR”
  },
  “voucherModeInfo” : {
  “voucherNumber” : “2424224242”
  },
  “walletModeInfo” : {
  “walletMid” : “2342424”,
  “walletMobileNumber” : “9818203333”,
  “walletRrn” : “2342424”,
  “walletTid” : “242424”,
  “walletTxnAmount” : 242424,
  “walletCardHolderName” : “SH RAM”,
  “walletMaskPan” : “4234xxxxxx4343”
  }
  “additionalInfoMap” : {
  key1”: “value1”,
  “key2”: “value2”
  }
}


WHERE,

Sr.No Fields Description Values
1 billIdentifier Third Party Bill Identifier String
2 plTransactionId Unique Identifier Of the Transaction in Pine Labs ecosystem. Format: Long Length: Numeric(19) Format: Long
Length: Numeric(19)
3 paymentMode See section Billing Server Payment Modes for possible values of payment modes. Format: Short Length: Numeric(2) Format: Short
Length: Numeric(2)
4 transactionTime Time when the transaction was recorded on the server. It will be the following format "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (Z is the time zone identifier in RFC 822 time zone). Format: String Format: String
5 transactionAmount Value in paise, total across all payment modes. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
6 cashModeInfo JSON object containing information about cash based transaction. Null if payment mode is not cash. 6.1 cashAmount Value in paise, when payment mode is Cash, 0 otherwise. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
7 cardModeInfo JSON object containing information about card based transaction. Null if payment mode is not card.
7.1 cardAmount Value in paise, when payment mode is Card. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
7.2 cardApprovalCode Approval code received from the bank. String String
7.3 cardMaskedNumber Masked Card Number. String String
7.4 cardTid Bank TID. String String
7.5 cardAcquirer Acquirer Name. String String
7.6 cardRrn RRN for the card transaction. String String
7.7 cardAcquirerMid Acquirer Mid. String String
7.8 cardHolderName Name of the card holder. String String
8 chequeModeInfo JSON object containing information about Cheque based transaction. Null if payment mode is not cheque.
8.1 chequeAmount Value in paise, when payment mode is Cheque. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
8.2 chequeNumber Present when payment mode is Cheque. Format: Integer Length: Numeric(6) Format: Integer
Length: Numeric(6)
8.3 chequeMicr Present when payment mode is Cheque. Format: Integer Length: Numeric(11) Format: Integer
Length: Numeric(11)
8.4 chequeDate Cheque Date, in ddMMyyyy format. Format: Integer Length: Numeric(8) Format: Integer
Length: Numeric(8)
8.5 chequeBank Present when payment mode is Cheque.
Bank Id Bank Name
1 State Bank of India
2 ICICI Bank
3 Punjab National Bank
4 Bank of Baroda
5 HDFC Bank
6 Canara Bank
7 Axis Bank
8 IDBI Bank
9 Union Bank of India
10 Others

Format: Integer
Length: Numeric(2)
9 qrBasedModeInfo JSON object containing information about QR-based transaction. Null if payment mode is not QR based.
9.1 qrAmount Value in paise, when payment mode is QR based. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
9.2 qrTranactionId Transaction Id received from QR Host. String String
9.3 qrHost QR Host Name. String String
10 voucherModeInfo JSON object containing information about voucher redemption based transaction. Null if payment mode is not voucher based
10.1 voucherNumber Voucher number used for redemption, String String
11 walletModeInfo JSON object containing information about wallet based payment transaction. Null if payment mode is not a wallet.
11.1 walletMid Wallet MID for the payment transaction. String String
11.2 walletMobileNumber Mobile Number linked to Wallet account, if applicable. String String
11.3 walletRrn RRN for this transaction. String String
11.4 walletTid TID for this transaction. String String
11.5 walletTxnAmount Transaction amount in paise. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
11.6 walletCardHolderName Card Holder name linked to the wallet account. String String
11.7 walletMaskPan Masked Card PAN linked to the wallet account. String String
12 additionalInfoMap Json Object representing additional information that might need to be passed. If any additional parameters are passed using this map, it will be communicated at the integration time.

Sample Response:


HTTP Method: POST
Request Headers:
                
                {
  “status” : 0,
  “reason” : null
}	


Sr.No Fields Description Values
1 status 0 denotes success, other values denote failure. Format: Integer Length: Numeric (2) Format: Integer
Length: Numeric (2)
2 reason Reason for the response. Must be populated where status is not 0. Format: String Length: Alphanumeric(1024) Format: String
Length: Alphanumeric(1024)

Please note
  1. The request packet would be retried only if a connection error is encountered during posting.
  2. Third Party must be able to save payment information for later processing even if they are unable to process the packet immediately.
  3. Third Party should build duplicate invocation check for this API.

Reverse Payment Details

After payment has been completed against the bill, it is possible for the payment to be reversed. This scenario can arise due to

  1. PoS User explicitly voiding the transaction.
    PoS User can VOID a transaction and thus reversing payment associated with it.
  2. Transaction getting automatically reversed due to hardware/network failure after chargeslip has been generated on the server.

Sample Request


HTTP Method: POST
Request Headers:
            
          X-PL-PoSId:3453453
        X-TP-ApiKey: apikey
        X-req-hash : ITTOC7fJr6bJcb7HVJUwVa1zss6GfOyfuuNHENu3GlY=
        Content-Type: application/json
X-PL-PoSId is the unique identifier for EDC machine in Pine Labs ecosystem. It can be used for whitelisting/blacklisting of EDC terminals.
X-TP-ApiKey is the secret API key issued by Third Party to Pine Labs. It is recommended that Third party whitelists the IPs of PL servers in production environment.
X-req-hash is HMAC-SHA256 digest of the request body. See section HMAC-SHA256 Message Digest Calculation for exact calculation methodology.

Endpoint:
                
               https://{tpserverhost}/reversePaymentInfo
Where
tpserverhost is the host/port info of the third party server.

Request Body:
                
              {
        “billIdentifier” : “23432423”, 
        “plTransactionId” : 32343,
        “reversedAmount” : 25345, 
        “reversalTime” : "2018-08-07T07:16:04.860+0530",
        “reversalReason” : “VOID”
        “additionalInfoMap” : {
        “key1”: “value1”,
        “key2”: “value2”
        }
        }
        


Sr. Fields Description Values
1 billIdentifier Third Party Bill Identifier String
2 plTransactionId Unique Identifier Of the Transaction in Pine Labs ecosystem. Format: Integer Length: Numeric(19) Format: Integer
Length: Numeric(19)
3 reversedAmount Value in paise. There is no concept of partial reversal. Entire amount is reversed. Format: Integer Length: Numeric(10) Format: Integer
Length: Numeric(10)
4 reversalTime Time when the transaction reversal was recorded on the server. It will be the following format "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (Z is the time zone identifier in RFC 822 time zone). Format: String Format: String
5 reversalReason Possible values are VOID and REVERSED String
6 additionalInfoMap Json Object representing additional information that might need to be passed. If any additional parameters are passed using this map, it will be communicated at the integration time.

Sample Response:


HTTP Method: POST
Request Headers:
              
        {
        “status” : 0,
        “reason” : null
        }	


Sr. Fields Description Values
1 status 0 denotes success, other values denote failure. Format: Integer Length: Numeric (2) Format: Integer
Length: Numeric (2)
2 reason Reason for the response. Must be populated where status is not 0. Format: String Length: Alphanumeric(1024) Format: String
Length: Alphanumeric(1024)

Please note
  1. The request packet would be retried only if a connection error is encountered during posting.
  2. Third Party must be able to save reversal information for later processing even if they are unable to process the packet immediately.
  3. Third Party should build duplicate invocation check for this API.

Note about API invocation order

Due to the distributed nature of the entire ecosystem (PoS, Pine Labs servers and Third Party Server), there is a probability, albeit very small, that API invocations of “Update Payment” and “Reverse Payment” may arrive out of order i.e. “Reverse Payment” invocation arrives before “Update Payment”. It is recommended that third-party keeps this in mind and develops their service accordingly.

Data Storage and Retention

  1. Only data related to identifying the bill and needed for printing on the charge slip is stored in the database.
  2. Any extra data should not be passed to the API. If passed, it is not stored in the database and discarded immediately.
  3. Any data which is sensitive in nature and not required for payment processing should not be passed in the API.
  4. Data retention period is 12 months since the date of transaction settlement. Older datasets are deleted.

HMAC-SHA256 Message Digest Calculation

HMAC-SHA256 is the hashing algorithm used. The secret key used will be shared at the beginning of the integration and will vary across different environments. The Third Party can calculate the hash using the algorithm specified above to validate the integrity as well authenticate that message originated at Pine Labs Servers.

Code snippet for Sample java code

        

Java


// Read the request body as a UTF-8 encoded character stream String requestBody = "queryParam1=paramValue1&queryParam2=paramValue2"; // Hashing algorithm String hmacAlgo = "HmacSHA256"; // Secret key is different for different environments String secretKey = "bQJwXNhFQxyWFSw8pAcsMiBlkabUlGyX"; javax.crypto.spec.SecretKeySpec key = new javax.crypto.spec.SecretKeySpec((secretKey).getBytes("UTF-8"), hmacAlgo); javax.crypto.Mac mac = javax.crypto.Mac.getInstance(hmacAlgo); mac.init(key); byte[] hashInBytes = mac.doFinal(requestBody.getBytes("UTF-8")); String digest = java.util.Base64.getUrlEncoder().encodeToString(hashInBytes); return digest;

Billing Server Payment Modes

Below are the possible values of payment mode in Billing Server.


Payment Mode Description
1 Cash
2 Credit/Debit Card
6 EMI
7 Voucher
10 Cheque
11 Wallet
12 UPI
13 Bharat QR