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.

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

          🗋
        X-PL-PoSId: 3453453
      X-TP-ApiKey: apikey
      X-req-hash: ITTOC7fJr6bJcb7HVJUwVa1zss6GfOyfuuNHENu3GlY=
      Content-Type: application/x-www-form-urlencoded

          🗋
        https://{tpserverhost}/fetchBillInfo

          🗋
        paramName1=paramValue1&paramName2=paramValue2

There can be a maximum of 3 input parameters.

Sample Response:

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

WHERE

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

            🗋
          X-PL-PoSId: 3453453
        X-TP-ApiKey: apikey
        X-req-hash: ITTOC7fJr6bJcb7HVJUwVa1zss6GfOyfuuNHENu3GlY=
        Content-Type: application/json

                🗋
              https://{tpserverhost}/updatePaymentInfo

                🗋
              {
  “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,

Sample Response:

                🗋
                {
  “status” : 0,
  “reason” : null
}	

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

            🗋
          X-PL-PoSId:3453453
        X-TP-ApiKey: apikey
        X-req-hash : ITTOC7fJr6bJcb7HVJUwVa1zss6GfOyfuuNHENu3GlY=
        Content-Type: application/json

                🗋
               https://{tpserverhost}/reversePaymentInfo

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

Sample Response:

              🗋
        {
        “status” : 0,
        “reason” : null
        }	

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
        Copy Code
        
        
        
// 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.