App to App Integration

1. Introduction

Plutus Smart or APOS (Android POS) is an Android-based smart transaction machine with ergonomic design, fast transaction speed and intuitive interface. Integrate it with your existing billing system for faster transaction speed.

Plutus Smart Integration allows you to access the following features:

• Carry-out sale transactions using multiple payment modes - credit card, debit card, wallet etc.
• Printing service to carry out bill, coupon, promotion printing using device printer
• Batch settlement
• View/get terminal profile info

2. Sample Use Case

• User selects products and checkout for payment.
• User selects payment mode and proceeds for payment.
• Billing App calls DoTransaction API with payment-amount.
• Plutus Smart processes the payment and prints charge slip.
• On receiving success response, Billing App calls PrintData API with invoice details.
• Plutus Smart prints the invoice and returns response.
• User receives invoice receipt.

3. Inter-application Communication

Billing application will communicate with Plutus Smart APIs for transactional and other Plutus-enabled features. For this communication, it will use Messenger over Bound Service.

In this process, the service defines a Handler that responds to different types of Message objects. This Handler is the basis for a Messenger that shares an IBinder with the client, allowing the client to send commands to the service using Message objects. Additionally, the client defines a Messenger of its own to send messages back. This technique allows the apps to perform Inter-Process Communication (IPC).

4. API Integration Process

4.1 API Integration Process for Native Apps

Messenger usage flow:

1. Plutus Smart will host a service that will implement a Handler for receiving call-back from Billing App.
2. This handler will create a Messenger object which further creates an IBinder object which Plutus Smart service returns to Billing App.
3. Billing App will use the IBinder object to create a Messenger object to send Messages.
4. The service running in Plutus Smart will receive each Message in JSON string format in its Handler and corresponding API action is performed.
5. After processing the API request, the service will respond back in JSON string format to Billing App using Messenger.

Sample Code for calling Plutus Smart API from Billing App

1. Billing App will bind to the Plutus Smart service Handler

  
Java
  Copy Code

Intent intent = new Intent();
intent.setAction(PLUTUS_SMART_ACTION);
intent.setPackage(PLUTUS_SMART_PACKAGE);
bindService(intent, connection, BIND_AUTO_CREATE);

2. After successful binding, the Service will respond to the ServiceConnection by returning to onServiceConnected(). A new messenger will be created using returned IBinder.

  
Java
  Copy Code

private ServiceConnection connection = new ServiceConnection() {
    @Override
    public void onServiceConnected(ComponentName name, IBinder service) {
        mServerMessenger = new Messenger(service);
        isBound = true;
    }
    
    @Override
    public void onServiceDisconnected(ComponentName name) {
        mServerMessenger = null;
        isBound = false;
    }
};

3. A message will be created and sent using the above mServerMessenger. This message will contain the API request information.

  
Java
  Copy Code

Message message = Message.obtain(null, MESSAGE_CODE);
Bundle data = new Bundle();
String value = "{\"Header\": {" +
    "\"ApplicationId\": \"abcdefgh\"," +
    "\"UserId\": \"user1234\"," +
    "\"MethodId\": \"1004\"," +
    "\"VersionNo\": \"1.0\"" +
"}}";
data.putString(BILLING_REQUEST_TAG, value);
message.setData(data);
try {
    message.replyTo = new Messenger(new IncomingHandler());
    mServerMessenger.send(message);
} catch (RemoteException e) {
    e.printStackTrace();
}

4. On receiving the response back from Service, Billing App will process the response in IncomingHandler.

  
Java
  Copy Code

private class IncomingHandler extends Handler {
    @Override
    public void handleMessage(Message msg) {
        Bundle bundle = msg.getData();
        String value = bundle.getString(BILLING_RESPONSE_TAG);
        // process the response Json as required.
    }
}

List of Constants:

4.2 API Integration Process for Hybrid Apps

Plutus Smart now supports communication with apps built on hybrid platform. For this communication to happen it will use Intents. The hybrid framework used to build the billing application can provide this functionality natively or can be achieved via help of a third-party plugin.

In this process, the hybrid application defines an intent with action as "com.pinelabs.masterapp.HYBRID_REQUEST" and the request JSON as extra payload. When adding the payload as extra, the client has to use the key as "REQUEST_DATA" and then use startActivityForResult() method to launch the intent. This intent is received by the server which internally binds to the service and process the request send by the client. The result is returned via the same calling intent, the client has to define onActivityResult() to receive the result from the server and use "RESPONSE_DATA" as the key to extract data from the intent.

Example of Intent object for DoTransactionRequest in a Hybrid Application:

  
Java
  Copy Code

String doTransactionPayload = 
    "{\"Detail\":{\"BillingRefNo\":\"TX12345678\",\"PaymentAmount\":9900,\"TransactionType\":4001}," +
    "\"Header\":{\"ApplicationId\":\"1001\",\"MethodId\":\"1001\",\"UserId\":\"userId\",\"VersionNo\":\"1.0\"}}";
    
Intent intent = new Intent("com.pinelabs.masterapp.HYBRID_REQUEST");
intent.putExtra("REQUEST_DATA", doTransactionPayload);
startActivityForResult(intent, REQUEST_CODE);

Note: The Request and the Response parameters will remain the same as in case of a native request. The only change is instead of using a messenger, we are passing data via extra in an Intent object.

5. Request – Header Information

Below are the parameters of Header which will be common for all API requests.

Sample Request

  
JSON
  Copy Code

{
    "Header": {
        "ApplicationId": "abcdefgh",
        "UserId": "user1234",
        "MethodId": "1001",
        "VersionNo": "1.0"
    }
}

6. Response – Header Information

Below are the parameters of Header data which will be common for all API responses.

Below are the parameters of Response data which will be common for the entire APIs response.

Sample Response

                
JSON
                Copy Code
              
              {
                  "Header": {
                      "ApplicationId": "abcdefgh",
                      "UserId": "user1234",
                      "MethodId": "1001",
                      "VersionNo": "1.0"
                  },
                  "Response": {
                      "ResponseCode": "0",
                      "ResponseMsg": "Success"
                  }
              }

7. API Details

7.1 DoTransaction

This API will be called when the Billing App completes the product selection and is ready to accept payment from the customer. Billing App will add all required tender options in its App, and call this API with specific tender such as Sale, Prepaid redeem etc.

This API can also be used for Load, Activation, Void transaction, etc. Refer Transaction Types for complete list of transactions supported.

7.1.1 Request Parameter

Sample JSON Request

7.1.1.1 Card Sale

For Sale Transaction of amount of Rs 99990.00 with Additional Info Details

                
JSON
                Copy Code
              
              {
"Header": {
"ApplicationId": "abcdefgh",
"UserId": "user1234",
"MethodId": "1001",
"VersionNo": "1.0"
},
"Detail": {
"TransactionType": "4001",
"BillingRefNo": "TXN12345678",
"PaymentAmount": "9999000",
"MobileNumberForEChargeSlip": "9876543210",
"AdditionalInfo": {
"Split1": "99991",
"Split2": "99992",
"Split3": "99993"
}
}
}

7.1.1.2 Void

                    
JSON
                    Copy Code
                  
                  {
    "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
    },
    "Detail": {
    "TransactionType": "4006",
    "BillingRefNo": "TXN12345678",
    "PaymentAmount": "9999000",
    "BankCode": "01",
    "InvoiceNo": "000012"
    }
    }
    

7.1.1.3 UPI Sale

                    
JSON
                    Copy Code
                  
                  {
    "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
    },
    "Detail": {
    "TransactionType": "4006",
    "BillingRefNo": "TXN12345678",
    "PaymentAmount": "9999000",
    "BankCode": "01",
    "InvoiceNo": "000012",
    }
    }

7.1.1.4 UPI Get Status

                    
JSON
                    Copy Code
                  
                  {
    "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
    },
    "Detail": {
    "TransactionType": "5122",
    "BillingRefNo": "TXN12345678",
    "PaymentAmount": "9999000"
    }
    }
    
    

7.1.2 Response Parameter

Sample JSON Response

                    
JSON
                    Copy Code
                  
                  
{
"Header": {
"ApplicationId": "1001",
"MethodId": "1001",
"UserId": "userId",
"VersionNo": "1.0"
},
"Response": {
"AppVersion": "250624",
"ParameterJson": "parameter",
"ResponseCode": 0,
"ResponseMsg": "APPROVED"
},
"Detail": {
"AcquirerName": "ICICI BANK",
"AcquiringBankCode": "02",
"ApprovalCode": "0",
"AuthAmoutPaise": "9900",
"BatchNumber": 60,
"BillingRefNo": "TX12345678",
"CardEntryMode": "CARD_CHIP",
"CardNumber": "************1461",
"CardType": "VISA",
"CardholderName": "PAVAN KUMAR",
"ExpiryDate": "XXXX",
"HostResponse": "APPROVED",
"InvoiceNumber": 262,
"LoyaltyPointsAwarded": 0,
"MerchantAddress": "JANAKPURI",
"MerchantCity": "NEW DELHI DEL ",
"MerchantId": " ",
"MerchantName": "LOVE COMMUNICATION",
"PlutusTransactionLogID": "4295355970",
"PlutusVersion":
"7B2243617264496E666F223A7B224163636F756E7454797065223A2243524544495422
2C2243617264436174656D",
"PosEntryMode": 2,
"PrintCardholderName": 1,
"Remark": "PROCESSED",
"RetrievalReferenceNumber": "000000000020",
"TerminalId": "09082023",
"TransactionDate": "06242025",
"TransactionTime": "154500",
"TransactionType": 4001,
"isTransitMode": false
}
}

UPI Sample JSON Response

                    
JSON
                    Copy Code
                  
                  
{
"Header": {
"ApplicationId": "1001",
"MethodId": "1001",
"UserId": "userId",
"VersionNo": "1.0"
},
"Response": {
"AppVersion": "250624",
"ParameterJson": "parameter",
"ResponseCode": 0,
"ResponseMsg": "APPROVED"
},
"Detail": {
"AcquirerName": "HDFC UPI",
"AcquiringBankCode": "2",
"AmountProcessed": "100",
"ApprovalCode": "321600",
"AuthAmoutPaise": "100",
"BatchNumber": 9053,
"BillingRefNo": "1245",
"CardType": "UPI",
"Cardtypevariant": "9053|113|1245",
"HostResponse": "APPROVED",
"InvoiceNumber": 113,
"LoyaltyPointsAwarded": 0,
"MerchantAddress": "ROOPALI HOTEL KALWA CHOWK ROOPALI HOTEL ",
"MerchantCity": "JUNAGADH",
"MerchantId": "HDFC000027203551",
"MerchantName": "Engineer auto center",
"PlutusTransactionLogID": "321600",
"PlutusVersion":
"7b22506c7574757356657273696f6e223a2276312e302e30222c2254786e496e666f22
3a7b2242617463684964223a223930",
"PrintCardholderName": 0,
"Remark": "APPROVED",
"TerminalId": "1000000667",
"TransactionDate": "06242025",
"TransactionTime": "155617",
"TransactionType": 5122,
"isTransitMode": false
}
}

UPI Get Status Sample JSON Response

                    
JSON
                    Copy Code
                  
                  
{
"Response": {
"ResponseCode": 100,
"ResponseMsg": "TRANSACTION INITIATED CHECK GET STATUS",
"AppVersion": "150",
"ParameterJson": "parameter"
},
"Header": {
"UserId": "***123**123***",
"VersionNo": "1.0",
"ApplicationId": "932e1a2d-59a5-4ac0-a368-ad011afbda38",
"MethodId": "1001"
},
"Detail": {
"Remark": "TRANSACTION INITIATED CHECK GET STATUS",
"PrintCardholderName": 0,
"PlutusVersion": "v1.0.0",
"AmountProcessed": "100",
"BillingRefNo": "OR158720200214-9-1",
"AcquirerName": "HDFC UPI",
"AcquiringBankCode": "2",
"TerminalId": "20000401",
"InvoiceNumber": 109,
"MerchantId": "HDFC000000649003",
"MerchantCity": "NOIDA",
"MerchantAddress": "Noida",
"TransactionTime": "155118",
"HostResponse": "TRANSACTION INITIATED CHECK GET STATUS",
"PineLabsBatchId": 100,
"TransactionDate": "02142020",
"MerchantName": "BFL_Store",
"PineLabsRoc": 5120,
"CardType": "UPI",
"BatchNumber": 9031,
"LoyaltyPointsAwarded": 0
}

7.2 Print Data

This API will be called when Billing App wants to print paper-receipt on Plutus Smart Device.

7.2.1 Request Parameter

Note: To support the dynamic font family in charge slip printing, we have added one parameter “FontFilePath” in Print API, to print the charge slip according to font family which is passed in API.

• If fontFilePath is passed to api, and if file exist at that location then charge slip will be printed according to passed font in API, otherwise default default will be use to print charge slip.
• For example, if font name is xyz.ttf and it is present in external storage without any folder, then pass FontFilePath as “xyz.ttf” in API.
• For example if font name is xyz.ttf and it is present

Sample JSON Request

                    
JSON
                    Copy Code
                  
                  
{
"Header": {
"ApplicationId": "abcdefgh",
"UserId": "user1234",
"MethodId": "1002",
"VersionNo": "1.0"
},
"Detail": {
"PrintRefNo": "123456789",
"SavePrintData": true,
"Data": [
{
"PrintDataType": "0",
"PrinterWidth": 24,
"IsCenterAligned": true,
"DataToPrint": "String Data",
"ImagePath": "0",
"ImageData": "0",
"fontSize": 15,
"lineSpacing": 0,
"textStyleType": 4
},
{
"PrintDataType": "1",
"PrinterWidth": 24,
"IsCenterAligned": true,
"DataToPrint": "",
"ImagePath": "Image Path",
"ImageData": "0"
},
{
"PrintDataType": "2",
"PrinterWidth": 24,
"IsCenterAligned": true,
"DataToPrint": "",
"ImagePath": "",
"ImageData": "Image Data String"
},
{
"PrintDataType": "3",
"PrinterWidth": 24,
"IsCenterAligned": true,
"DataToPrint": "Bar Code Data in String",
"ImagePath": "",
"ImageData": ""
},
{
"PrintDataType": "4",
"PrinterWidth": 24,
"IsCenterAligned": true,
"DataToPrint": "QR Code Data in String",
"ImagePath": "",
"ImageData": ""
}
]
}
}

7.2.2 Response Parameter

Sample JSON Response

                    
JSON
                    Copy Code
                  
                  
{
"Header": {
"ApplicationId": "abcdefgh",
"UserId": "user1234",
"MethodId": "1002",
"VersionNo": "1.0"
},
"Response": {
"ResponseCode": "0",
"ResponseMsg": "Success"
},
"Detail": {
"AppVersion": "Plutus v1.5"
}
}

7.3 Settlement

There are two ways to settle the current batch of payment transactions:

• Settlement API can be used to settle current batch in Plutus Smart App. On calling this API and successful response, charge slip will be printed on the terminal.
• User can go to Plutus Smart App menu to manually settle the batch.

7.3.1 Request Parameter

Sample JSON Request

  
JSON
  Copy Code

 {
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1003",
    "VersionNo": "1.0"
  }
}

7.3.2 InResponse Parameter

Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1003",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "SettlementSummary": [
      {
        "BatchName": "HDFC",
        "AcquirerCode": "01",
        "TID": "01000234",
        "MID": "123411234",
        "CreditCount": 10,
        "CreditAmount": 502100,
        "DebitCount": 5,
        "DebitAmount": 324000
      },
      {
        "BatchName": "ICICI",
        "AcquirerCode": "02",
        "TID": "013000123",
        "MID": "123411224",
        "CreditCount": 1,
        "CreditAmount": 2100,
        "DebitCount": 0,
        "DebitAmount": 324000
      }
    ]
  }
}

7.4 Get Terminal Info

This API will be called when the Billing App wants to get terminal details configured on Plutus Smart Device. It is an optional API, can be used to fetch and display store information on Billing App.

7.4.1 Request Parameter

Sample JSON Request

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1004",
    "VersionNo": "1.0"
  }
}

7.4.2 Response Parameter

Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1005",
    "VersionNo": "1.0"
  },
  "Detail": {
    "BaseSerialNumber": "121234"
  }
}

7.5 Connect Bluetooth

This API will be called when the Billing App wants to connect Bluetooth on Plutus Smart Device.

7.5.1 Request Parameter

Sample JSON Request

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1005",
    "VersionNo": "1.0"
  },
  "Detail": {
    "BaseSerialNumber": "121234"
  }
}

7.5.2 Response Parameter

Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1005",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  }
}

7.6 Disconnect Bluetooth

This API will be called when the Billing App wants to Disconnect Bluetooth on Plutus Smart Device.

7.6.1 Request Parameter

Sample JSON Request

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1006",
    "VersionNo": "1.0"
  }
}

7.6.2 Response Parameter

Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1006",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Bluetooth Disconnection Success"
  }
}

7.7 Scan QR Code/Barcode

This API will be called when the Billing App wants to do single or multi scan any QR/Barcode on Plutus Smart Device.

7.7.1 Scan Request Parameter

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1007",
    "VersionNo": "1.0"
  }
}

7.7.2 Scan Response Parameter

Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1007",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "ScannedData": "2345"
  }
}

7.8 Upload Invoice

This API uploads an invoice data coming from the Billing App to the server.

7.8.1 Request Parameter

Sample JSON Request

  
JSON
  Copy Code

{
  "Detail": {
    "BillingUserName": "nikhil",
    "Customer": {
      "AddressLine1": "E-block, Sector-62",
      "AddressLine2": "",
      "City": "Noida",
      "Country": "India",
      "DOB": "1992-06-13",
      "Email": "himanshu@gmail.com",
      "FirstName": "Himanshu",
      "Gender": "MALE",
      "LastName": "Jain",
      "Phone": 8506062503,
      "PinCode": 201309,
      "State": "Uttar Pradesh"
    },
    "DiscountTotalValue": 50,
    "GrossBill": 5500,
    "InvoiceNumber": 1,
    "NetBill": 5000,
    "OrderCreationTimeLocal": "2019-04-01",
    "OrderId": "OR-123-1",
    "PaymentStatus": "PAID",
    "Payments": [
      {
        "Amount": 2000,
        "CardType": "",
        "PaymentId": "123",
        "PaymentType": "PAYMENT_CASH"
      },
      {
        "Amount": 3500,
        "CardType": "CARD_VISA",
        "PaymentId": "456",
        "PaymentType": "PAYMENT_CARD"
      }
    ],
    "Products": [
      {
        "AdditionalChargeValue": 0,
        "BarCode": 0,
        "DiscountTotalValue": 50,
        "ProductBasePrice": 1000,
        "ProductId": "PROD2001",
        "ProductName": "Food Packet",
        "ProductValue": 5500,
        "Quantity": 5,
        "SkuId": 0,
        "TaxTotalValue": 100,
        "VoidAmount": 0,
        "VoidQuantity": 0
      }
    ],
    "Status": "DELIVERED",
    "Taxes": 100
  },
  "Header": {
    "ApplicationId": "1001",
    "MethodId": "1008",
    "UserId": "1234",
    "VersionNo": "1.0"
  }
}

7.8.2 Response Parameter

Sample JSON Response

  
JSON
  Copy Code

{
    "ApplicationId": "1001",
    "UserId": "userId",
    "MethodId": "1008",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "TerminalLogId": 2,
    "TerminalId": "30000001"
  }

7.9 Single/Multi Scan QR/Barcode Code from Camera

This API will be called when the Billing App wants to do single/multi scan any QR/Barcode through Camera on Plutus Smart Device.

7.9.1 Request Parameter

Single Scan Sample JSON Request

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1009",
    "VersionNo": "1.0"
  }
}

Multi Scan Sample JSON Request

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1010",
    "VersionNo": "1.0"
  }
}

7.9.2 Response Parameter

Single Scan Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1009",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "ScannedData": "2345"
  }
}

Multi Scan Sample JSON Response

  
JSON
  Copy Code

{
  "Detail": {
    "ScannedDataList": [
      {
        "itemCount": 10,
        "itemValue": "\\000026https://www.samsung.com/au/support/"
      },
      {
        "itemCount": 12,
        "itemValue": "http://en.m.wikipedia.org"
      },
      {
        "itemCount": 17,
        "itemValue": "http://bit.ly/GiraDischi"
      }
    ]
  },
  "Header": {
    "ApplicationId": "1001",
    "MethodId": "1010",
    "UserId": "userId",
    "VersionNo": "1.0"
  },
  "Response": {
    "AppVersion": "161",
    "ParameterJson": "parameter",
    "ResponseCode": 0,
    "ResponseMsg": "Data Scanned Success"
  }
}

7.10 Transit Mode (NCMC) Transactions Support

This section describes the API support for Transit Mode (NCMC) transactions.

Request Parameters details

Response Parameters Details

7.10.1 Offline Purchase

For Sale Transaction of amount of Rs 115.00

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Detail": {
    "TransactionType": "4001",
    "serviceID": "1010",
    "serviceMI": "9100",
    "isTransitMode": true,
    "serviceData": "Service Data (max 96 bytes)",
    "BillingRefNo": "TXN12345678",
    "PaymentAmount": "11500"
  }
}

Response Sample

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "BillingRefNo": "105",
    "TransactionType": 4001,
    "AuthAmountPaise": "100",
    "CardNumber": "438624*******2802",
    "ExpiryDate": "0406",
    "CardholderName": "AMITMOHAN",
    "CardType": "RUPAY",
    "InvoiceNumber": 11,
    "PlutusTransactionLogID": "4296309778",
    "TransactionDate": "02012011",
    "TransactionTime": "210403",
    "PineLabsClientId": 12345,
    "PineLabsBatchId": 9002,
    "PineLabsRoc": 105,
    "serviceID": "1010",
    "cardBalance": 7690
  }
}

7.10.2 Service Creation

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Detail": {
    "TransactionType": "4122",
    "serviceID": "1010",
    "serviceMI": "9100",
    "isTransitMode": true,
    "serviceData": "Service Data (max 96 bytes)",
    "BillingRefNo": "TXN12345678"
  }
}

Response Sample

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "BillingRefNo": "105",
    "TransactionType": 4122,
    "CardNumber": "438624*******2802",
    "ExpiryDate": "0406",
    "CardholderName": "AMITMOHAN",
    "CardType": "RUPAY",
    "InvoiceNumber": 11,
    "PlutusTransactionLogID": "4296309778",
    "TransactionDate": "02012011",
    "TransactionTime": "210403",
    "PineLabsClientId": 12345,
    "PineLabsBatchId": 9002,
    "PineLabsRoc": 105,
    "serviceID": "1010"
  }
}

7.10.3 Load Money

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Detail": {
    "TransactionType": "4119",
    "serviceID": "1010",
    "serviceMI": "9100",
    "isTransitMode": true,
    "serviceData": "Service Data (max 96 bytes)",
    "paymentMode": "CASH/ACCOUNT",
    "BillingRefNo": "TXN12345678",
    "PaymentAmount": "11500"
  }
}

Response Sample

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "BillingRefNo": "105",
    "TransactionType": 4119,
    "AuthAmountPaise": "100",
    "CardNumber": "438624*******2802",
    "ExpiryDate": "0406",
    "CardholderName": "AMITMOHAN",
    "CardType": "RUPAY",
    "InvoiceNumber": 11,
    "PlutusTransactionLogID": "4296309778",
    "TransactionDate": "02012011",
    "TransactionTime": "210403",
    "PineLabsClientId": 12345,
    "PineLabsBatchId": 9002,
    "PineLabsRoc": 105,
    "paymentMode": "CASH/ACCOUNT",
    "serviceID": "1010",
    "cardBalance": 7690
  }
}

7.10.4 Balance Update

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Detail": {
    "TransactionType": "4120",
    "serviceID": "1010",
    "serviceMI": "9100",
    "isTransitMode": true,
    "serviceData": "Service Data (max 96 bytes)",
    "BillingRefNo": "TXN12345678"
  }
}

Response Sample

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "BillingRefNo": "105",
    "TransactionType": 4120,
    "CardNumber": "438624*******2802",
    "ExpiryDate": "0406",
    "CardholderName": "AMITMOHAN",
    "CardType": "RUPAY",
    "InvoiceNumber": 11,
    "PlutusTransactionLogID": "4296309778",
    "TransactionDate": "02012011",
    "TransactionTime": "210403",
    "PineLabsClientId": 12345,
    "PineLabsBatchId": 9002,
    "PineLabsRoc": 105,
    "serviceID": "1010",
    "cardBalance": 7690
  }
}

7.10.5 Balance Enquiry

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Detail": {
    "TransactionType": "4121",
    "serviceID": "1010",
    "serviceMI": "9100",
    "isTransitMode": true,
    "serviceData": "Service Data (max 96 bytes)",
    "BillingRefNo": "TXN12345678"
  }
}

Response Sample

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1001",
    "VersionNo": "1.0"
  },
  "Response": {
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  },
  "Detail": {
    "BillingRefNo": "105",
    "TransactionType": 4121,
    "CardNumber": "438624*******2802",
    "ExpiryDate": "0406",
    "CardholderName": "AMITMOHAN",
    "CardType": "RUPAY",
    "InvoiceNumber": 11,
    "PlutusTransactionLogID": "4296309778",
    "TransactionDate": "02012011",
    "TransactionTime": "210403",
    "PineLabsClientId": 12345,
    "PineLabsBatchId": 9002,
    "PineLabsRoc": 105,
    "serviceID": "1010",
    "effDate": "yyMMdd",
    "serviceData": "Service Data (max 96 bytes)"
  }
}

7.11 Additional Settings Request

We are introducing an additionalSettings object in the API request to allow flexible feature control. Initially, this object will support the key:

• kiosk_mode: true or false
  When set to true, the device will enter kiosk mode. When set to false, kiosk mode will be disabled.

This structure is designed to be extensible, so additional keys can be added in the future without breaking existing integrations. Any new actions or controls will follow the same pattern under the additionalSettings object.

7.11.1 Request Parameter

Sample JSON Request

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1018",
    "VersionNo": "1.0"
  },
  "Detail": {
    "additionalSettings": {
      "kiosk_mode": true
    }
  }
}

7.11.2 Response Parameter

Sample JSON Response

  
JSON
  Copy Code

{
  "Header": {
    "ApplicationId": "abcdefgh",
    "UserId": "user1234",
    "MethodId": "1018",
    "VersionNo": "1.0"
  },
  "Response": {
    "AppVersion": "010125",
    "ResponseCode": "0",
    "ResponseMsg": "Success"
  }
}

8. Printing Via Browser

This Api will be used to print charge slip via browser

Sample Request URL

                
JSON
                Copy Code
              
              masterapp://pinelabs?reqPath=download/data.json&resPath=http://192.168.1.0:5500/html3
            

Request Parameters details

Sample Response

          
JSON
          Copy Code
        
        http:192.168.1.0:5500/merchant.html?resCode=0&resMsg=Print%20Successful
        

Response Parameters details

Request Handling (Merchant Web):

The merchant’s web application constructs a deeplink URL to request the terminal to print a charge slip.

          
JSON
          Copy Code
        
        //filename – file path
          //userInputTest – Response Url
          setTimeout(function() {
          const path =
          masterapp://pinelabs?reqPath=download/${fileName}&resPath=${userInputText};
          window.open(path);
          }, 500);

Response Handling (Merchant Web):

When the terminal finishes processing the charge slip, it will return a resCode and resMsg to the resPath. The merchant’s web page can capture this response.

    
JSON
    Copy Code
    
<script type="text/javascript">
          function getQueryParam(name) {
          var urlParams = new URLSearchParams(window.location.search);
          return urlParams.get(name);
          }
          // Extract data from the URL when the page loads
          window.onload = function() {
          var data = getQueryParam('resMsg');
          if (data) {
          alert("Received data from the app: " + data); // Handle the data from the app
          setTimeout(function() {
          window.close(); // Close the page after 5 seconds
          }, 2000); // 5000 milliseconds (5 seconds)
          window.onbeforeunload = function() {
          window.close(); // Close the window when the user clicks OK
          };
          }
          };
          </script>

9. Security Requirement

Following minimum requirements should be ensured for all existing or new Third party service providers:

1. Due diligence should be performed on vendor financial stability before an agreement is entered with Third party service provider. Pine Labs and Third party may enter in escrow agreement in case of any issues.
2. Non-disclosure agreement (NDA) to be executed between Pine Labs and Third-party service provider:
   • Pine Labs defined NDA shall be executed with Third party service provider but not limited to liabilities, security and confidentiality requirements.
3. Application Security Assessment document:
   1. Application Secure Code Review Report: Application secure code review report shall be obtained from vendor which would have been tested against OWASP and SANS and the same shall be shared with Information Security group before testing.
   2. Application Pentest Report: Application penetration testing report and assessment report should be obtained from Third party service provider which is tested against OWASP & SANS requirement. The same shall be shared with Information Security group before testing.
4. Business should review change management process in place with Third party service provider.
5. Business should review processes in place by Third party service provider to periodically share patches for applications to minimize risks to Pine Labs.
6. Following technical controls should be evaluated by Business such as:
   • Application interface authentication
   • Data masking techniques
   • RESTful API's
7. Security Assessment Ownership and Requisite: Security assessment on Third party application will be under ownership of Pine Labs information security team. QA team shall provide following details for Security Assessment:

   Sr. No.	Question	Response
   1	Company Name	3rd Party Name
   2	Application Details	Complete use case of Application
   3	Request and Response Parameter
   4	Application Login Account	username and password

8. Security Assessment by Pine Labs: Post Compliance to above mentioned requirements from A to F, Information security group at Pine Labs will conduct an assessment on the application to identify security-related weaknesses in the application as per OWASP & SANS guidelines.
9. Internal Approval: Pine Labs Security team also requires approval from Integration Team Head before initiating any signing or security Assessment of application.

10. Glossary

10.1 Response Code

For all API successful responses, Response Code will be set to zero.

10.2 Method ID's

These Method ID's need to use in request parameter to perform different actions.

10.3 Transaction Types

These transaction type values can be use in DoTransaction Method ID to perform different transactions.

11. References

• Terminal Setup Docs: Click Here
• SDKs and Sample Applications Links: Click Here
• FAQs: Click Here