This section outlines the interface and message specifications enabling a direct connection between a Merchant Billing Application and Pine Labs Android Payment Application without any intermediary applications or libraries such as PoSLib or PoS Controller.
In this direct integration approach, the Merchant Billing Application should take care of constructing the CSV request in accordance with the provided specifications and communicates directly with the Android Payment Application.
Note:
Only COM-based communication is supported in direct integration.
The following diagram illustrates at high level the message flow between the devices
Merchant billing application should communicate with PoSBridge to perform transactions with Pine labs Payment application.
The supported physical interfaces for wired integration between the billing application and the android terminal include USB/Serial cable and USB Type C cable.
The following table describes the default serial port communications protocol
Data Rate | 115200 bps |
---|---|
Connection |
USB/Serial Cable (RS232)
USB Type C On a PC, this is compatible with any of the available port |
Mode | Terminal port is full duplex |
Transmission | Asynchronous, 8 data bits, no parity, 1 stop bit (N,8,1) |
Characters | ASCII character set (for character fields) |
The messages that are transmitted over the COM/Serial cable between the PoS and the Terminal will use the following structure. Both request and response messages exchanged should follow the same structure.
All messages are framed with STX and ETX characters and are followed by a longitudinal redundancy check byte (LRC). Merchant billing application should make sure to validate the LRC before processing request/response.
STX | Message Data | ETX | LRC |
LRC |
Element | Length | Value | Description |
---|---|---|---|
STX | 1 | 0x02 | Start of text - Signals start of message |
Message Data | Variable | The message data consists of:
|
|
ETX | 1 | 0x03 | End of text – Signals end of message |
LRC | 1 | XOR of all characters excluding STX and ETX |
CSV requests and responses, data fields are separated by commas (,). There are 23 fields in total, where some are mandatory while others are optional depending on the transaction type.
For instance, in a sale request, fields 1 and 3 are mandatory, and the merchant billing application must provide the data for these fields. The remaining fields, which are optional, can either be filled with data or left empty based on specific requirements.
Example:
4001,,1000
Here's an example for a sale request, if the merchant billing application need to send fields 1, 2, 3, and 16, where 2 and 16 are optional, it can leave fields 4 to 15 empty using commas, like this:
Example:
4001,2,1000,,,,,,,,,,,,,16
In the above example, field 1 represents the transaction code, field 3 represents the transaction amount, and fields 2 and 16 are optional and filled as needed. The remaining fields from 4 to 15 are left empty with commas.
Below tables describe the request and response parameters of Message Data.
Content | Type | Length | Description |
---|---|---|---|
STX | BYTE | 1 | 0x02 |
Source ID | BYTE | 2 | Identification Number for client (e.g., 0x1000) |
Function Code | BYTE | 2 | As defined in APIs |
Data Length | BYTE | 2 | Length of Message data excluding ETX and STX |
Request Data | ASCII | VARIABLE | Transaction Specific Request Data in CSV. Refer APIs |
ETX | BYTE | 1 | 0x03 |
LRC | BYTE | 1 | LRC Calculation |
0210000997001D343030312C545831323334353637382C3130313030302C2C2C2C2C2C2C036D
Below is the breakdown of sample request
Element | Value |
---|---|
STX | 02 |
Source ID | 10 00 |
Function Code | 09 97 |
Data Length | 00 1D |
Request Data | 34 30 30 31 2C 54 58 31 32 33 34 35 36 37 38 2C 31 30 31 30 30 30 2C 2C 2C 2C 2C 2C 2C |
ETX | 03 |
LRC | 6D |
Content Type | Type | Length | Description |
---|---|---|---|
STX | BYTE | 1 | 0x02 - Start of text - Signals start of message |
Source ID | BYTE | 2 | Identification Number for client (e.g., 0x1000) |
Function Code | BYTE | 2 | Refer APIs |
Error Code | BYTE | 2 | 0x0001 - valid response, 0x0000 - invalid response |
Data Length | BYTE | 2 | E.g. 0x0032 for a data length of 50 bytes |
Response Data | ASCII | VARIABLE | If Error code is 0X0001, response data sent from payment application in CSV. Refer APIs. If Error code is 0x0000, resopnse data send from payment application is error message. |
ETX | BYTE | 1 | 0xFF - End of text - Signals end of message |
LRC | BYTE | 1 |
Sucess Sample Raw Response:Java
byte calcLrc = LrcUtil.calcLRC(Utils.convertAsciiToBcd("10000997001D343030312C545831323334353637382C3130302C2C2C2C2C2C2CFF")); public static byte[] convertAsciiToBcd(String asciiString) { // Ensure the input string has an even length if (asciiString.length() % 2 != 0) { throw new IllegalArgumentException("Input string length must be even"); } int length = asciiString.length(); byte[] bcdResult = new byte[length / 2]; for (int i = 0; i < length; i += 2) { char highNibble = asciiString.charAt(i); char lowNibble = asciiString.charAt(i + 1); // Convert ASCII characters to binary int highNibbleValue = Character.digit(highNibble, 16); int lowNibbleValue = Character.digit(lowNibble, 16); // Combine the nibbles into a BCD byte byte bcdByte = (byte) ((highNibbleValue << 4) | lowNibbleValue); // Store the BCD byte in the result array bcdResult[i / 2] = bcdByte; } return bcdResult; } public static byte calcLRC(byte[] message) { int len; byte lrc for (len = 0, lrc = 0x00; len < message.length; len++) { lrc ^= message[len]; } logger.info("message:" + StringUtil.byte2HexStr(message) + "\n ,Calculated LRC=" + String.format("%X", lrc)); return lrc; }
Java
02999919970001015E012254583132333435363738222C223030222C22415050524F564544222C222A2A2A2A2A2A2A2A2A2A2A2A36373933222C2258585858222C224E494B48494C205020504154494C20202020202020202020202F222C2256495341222C313131382C32332C223939383030303236222C302C2250524F434553534544222C2249434943492042414E4B222C22202020202020202020202020202020222C22303030303030303030303230222C322C312C224C4F564520434F4D4D554E49434154494F4E222C224A414E414B50555249222C224E45572044454C48492020202044454C20202020202020222C22506C757475732076322E3132204D542049434943492042414E4B222C30322C22222C22222C22222C22222C22222C22222C22222C22222C22222C223036323332303233222C22313334333131222C2234323935323233303633222C22313030222C2234303031222C22434152445F434849502203C6
Below is the breakdown of sample request
Element | Value |
---|---|
STX | 02 |
Source ID | 99 99 |
Message Type | 19 97 |
Error Code | 00 01 |
Data Length | 01 5E |
Response Data | 01 22 54 58 31 32 33 34 35 36 37 38 22 2C 22 30 30 22 2C 22 41 50 50 52 4F 56 45 44 22 2C 22 2A 2A 2A 2A 2A 2A 2A 2A 2A 2A 2A 2A 36 37 39 33 22 2C 22 58 58 58 58 22 2C 22 4E 49 4B 48 49 4C 20 50 20 50 41 54 49 4C 20 20 20 20 20 20 20 20 20 20 20 20 20 2F 22 2C 22 56 49 53 41 22 2C 31 31 31 38 2C 32 33 2C 22 39 39 38 30 30 30 32 36 22 2C 30 2C 22 50 52 4F 43 45 53 53 45 44 22 2C 22 49 43 49 43 49 20 42 41 4E 4B 22 2C 22 20 20 20 20 20 20 20 20 20 20 20 20 20 20 22 2C 22 30 30 30 30 30 30 30 30 30 30 32 30 22 2C 32 2C 31 2C 22 4C 4F 56 45 20 43 4F 4D 4D 55 4E 49 43 41 54 49 4F 4E 22 2C 22 4A 41 4E 41 4B 50 55 52 49 22 2C 22 4E 45 57 20 44 45 4C 48 49 20 20 20 20 44 45 4C 20 20 20 20 20 20 20 22 2C 22 50 6C 75 74 75 73 20 76 32 2E 31 32 20 4D 54 20 49 43 49 43 49 20 42 41 4E 4B 22 2C 30 32 2C 22 22 2C 22 22 2C 22 22 2C 22 22 2C 22 22 2C 22 22 2C 22 22 2C 22 22 2C 22 30 36 32 33 32 30 32 33 22 2C 22 31 33 34 33 31 31 22 2C 22 34 32 39 35 32 32 33 30 36 33 22 2C 22 31 30 30 22 2C 22 34 30 30 31 22 2C 22 43 41 52 44 5F 43 48 49 50 22 |
ETX | 03 |
LRC | C6 |
02999919970000001300436172642072656164696E67204572726F720383
Below is the breakdown of sample request
Element | Value |
---|---|
STX | 02 |
Source ID | 99 99 |
Message Type | 19 97 |
Error Code | 00 00 |
Data Length | 00 13 |
Response Data | 00436172642072656164696E67204572726F72 |
ETX | 03 |
LRC | 83 |
This section describes the sample request and response payload for supported transactions.
Below is the sale sample Request and Response (For Request data please refer APIs )
Request
HEX String Format |
ASCII Format
|
---|---|
210000997001D343030312C545831323334353637382C3130313030302C2C2C2C2C2C2CFF0341
|
— 4001,TX12345678,101000,,,,,,,ÿ
|
Success Response
HEX String Format |
ASCII Format
|
---|---|
02999919970001015E012254583132333435363738222C223030222C22415050524F564544222C222A2A2A2A2A2A2A2A2A2A2A2A36373933222C2258585858222C224E494B48494C205020504154494C20202020202020202020202F222C2256495341222C313131382C32332C223939383030303236222C302C2250524F434553534544222C2249434943492042414E4B222C2220202020202020202020202020202020222C22303030303030303030303230222C322C312C224C4F564520434F4D4D554E49434154494F4E222C224A414E414B50555249222C224E45572044454C48492020202044454C2020202020202020222C22506C757475732076322E3132204D542049434943492042414E4B222C30322C22222C22222C22222C22222C22222C22222C22222C22222C22222C22222C223036323332303233222C22313334333131222C2234323935323233303633222C22313030222C2234303031222C22434152445F434849502203C6
|
™™— ^"TX12345678","00" ,"APPROVED","***** *******6793","XXXX","NIKHIL P
PATIL /","VISA",1118,23,"99800026",0,"PROCESSED","ICICI BANK","
","000000000020",2, 1,"LOVE COMMUNICATION","J ANAKPURI","NEW DELHI DEL
","Plutus v2.12 MT ICICI BANK",02,"","","","","",
"","","","","","06232023","134311","4295223063","100","4001","CARD_CHIP"ÿ
|
Failure Response
HEX String Format |
ASCII Format
|
---|---|
02999919970000001300436172642072656164696E67204572726F720383
|
™™— Card reading Errorƒ
|
DCC Request
HEX String Format |
ASCII Format
|
---|---|
210000997001D343030312C545831323334353637382C3130313030302C2C2C2C2C2C2CFF0341
|
— 4001,TX12345678,101000,,,,,,,ÿ
|
DCC Response
HEX String Format |
ASCII Format
|
---|---|
0299991997000101AD012254583132333435363738222C223030222C22415050524F564544222C222A2A2A2A2A2A2A2A2A2A2A2A36373933222C2258585858222C224E494B48494C205020504154494C20202020202020202020202F222C2256495341222C313131382C32332C223939383030303236222C302C2250524F434553534544222C2249434943492042414E4B222C2220202020202020202020202020202020222C22303030303030303030303230222C322C312C224C4F564520434F4D4D554E49434154494F4E222C224A414E414B50555249222C224E45572044454C48492020202044454C2020202020202020222C22506C757475732076322E3132204D542049434943492042414E4B222C30322C22222C22222C22222C22222C22222C22222C22222C22222C22222C22222C223036323332303233222C22313334333131222C2234323935323233303633222C22313030222C2234303031222C22434152445F43484950222C22222C22222C22414544222C2231312E3131222C2231322E3131222C223131222C22413030303030303030333130222C223438303030222C22413246384344304331303746393130220322
|
™™— "TX12345678","00","APPROVED","************6793","XXXX","NIKHIL P PATIL /","VISA",1118,23,"99800026",0,"PROCESSED","ICICI BANK"," ","000000000020",2,1,"LOVE COMMUNICATION","JANAKPURI","NEW DELHI DEL ","Plutus v2.12 MT ICICI BANK",02,"","","","","","","","","","","06232023","134311","4295223063","100","4001","CARD_CHIP","","","AED","11.11","12.11","11","A00000000310","48000","A2F8CD0C107F910""
|
JSON Request: |
|
JSON Response: |
|
Below is the Refund sample Request and Response (For Request data please refer APIs ).
Request
HEX String Format |
ASCII Format
|
---|---|
0210000997001A343030322C545831323334353637382C3130302C2C2C2C2C2C2C038B
|
— 4002,TX12345678,100,,,,,,,ÿ
|
Response
HEX String Format |
ASCII Format
|
---|---|
029999199700010179012254583132333435363738222C22222C225472616E73616374696F6E206E6F7420737570706F7274656420666F72207468652073656C6563746564206163717569726572222C222A2A2A2A2A2A2A2A2A2A2A2A35313834222C2258585858222C22222C2220222C302C302C223939383030303236222C302C225472616E73616374696F6E206E6F7420737570706F7274656420666F72207468652073656C6563746564206163717569726572222C2249434943492042414E4B222C22202020202020202020202020202020222C22303030303030303030303030222C322C312C224C4F564520434F4D4D554E49434154494F4E222C224A414E414B50555249222C224E45572044454C48492020202044454C20202020202020222C22506C757475732076322E3132204D542049434943492042414E4B222C30322C22222C22222C22222C22222C22222C22222C22222C22222C22222C22222C2230222C22313030222C2234303032222C22434152445F43484950220396
|
™™— y"TX12345678","","Transaction not supported for the selected
acquirer","********5184","XXXX",""," ",0,0,"99800026",0,"Transaction not
supported for the selected acquirer","ICICI BANK","
","000000000000",2,1,"LOVE COMMUNICATION","JANAKPURI","NEW DELHI DEL
","Plutus v2.12 MT ICICI
BANK",02,"","","","","","","","","","","","","","0","100","4002","CARD_CHIP"ÿ
|
JSON Request: |
|
JSON Response: |
|
Below is the Void sample Request and Response (For Request data please refer APIs ).
Request
HEX String Format |
ASCII Format
|
---|---|
0210000997001A343030362C545831323334353637382C3130302C2C2C2C2C2C2C038F
|
— 4006,TX12345678,100,,,,,,,ÿ
|
Response
HEX String Format |
ASCII Format
|
---|---|
02999919970001003701496E76616C696420496E766F696365204E756D626572206F722064657461696C7320666F722074686973207472616E73616374696F6E039C
|
™™— 7Invalid Invoice Number or details for this transactionÿ
|
JSON Request: |
|
JSON Response: |
|
Below is the Pre-Auth sample Request and Response (For Request data please refer APIs ).
Request
HEX String Format |
ASCII Format
|
---|---|
0210000997001A343030372C545831323334353637382C3130302C2C2C2C2C2C2C038E
|
— 4007,TX12345678,100,,,,,,,ÿ
|
Response
HEX String Format |
ASCII Format
|
---|---|
029999199700010144012254583132333435363738222C223030222C22415050524F564544222C222A2A2A2A2A2A2A2A2A2A2A2A35313834222C2258585858222C22222C2256495341222C313132322C32332C223939383030303236222C302C2250524F434553534544222C2249434943492042414E4B222C22202020202020202020202020202020222C22303030303030303030303230222C322C312C224C4F564520434F4D4D554E49434154494F4E222C224A414E414B50555249222C224E45572044454C48492020202044454C20202020202020222C22506C757475732076322E3132204D542049434943492042414E4B222C30322C22222C22222C22222C22222C22222C22222C22222C22222C22222C22222C223036323332303233222C22313535323237222C2234323935323233313437222C22313030222C2234303037222C22434152445F43484950220332
|
™™—
D"TX12345678","00","APPROVED","*********5184","XXXX","","VISA",1122,23,"99800026",0,"PROCESSED","ICICI
BANK"," ","000000000020",2,1,"LOVE COMMUNICATION","JANAKPURI","NEW DELHI
DEL ","Plutus v2.12 MT ICICI
BANK",02,"","","","","","","","","","","","","","06232023","155227","4295223147","100","4007","CARD_CHIP"ÿ
|
JSON Request: |
|
JSON Response: |
|
Below is the Sale Complete sample Request and Response (For Request data please refer APIs ).
Request
HEX String Format |
ASCII Format
|
---|---|
210000997001A343030382C545831323334353637382C3130302C2C2C2C2C2C2C0381
|
— 4008,TX12345678,100,,,,,,,ÿ
|
Response
HEX String Format |
ASCII Format
|
---|---|
02999919970001010C012254583132333435363738222C22222C22496E76616C696420496E766F696365204E756D626572206F722064657461696C7320666F722074686973207472616E73616374696F6E222C22222C2258585858222C22222C2220222C313132322C302C2220222C302C22496E76616C696420496E766F696365204E756D626572206F722064657461696C7320666F722074686973207472616E73616374696F6E222C2242414E4B222C2220222C22303030303030303030303030222C312C312C2220222C2220222C2220222C22312E312E312E31222C30302C22222C22222C22222C22222C22222C22222C22222C22222C22222C22222C22222C2230222C22313030222C2234303038222C22220382
|
™™— "TX12345678","","Invalid Invoice Number or details for this
transaction","","XXXX",""," ",1122,0," ",0,"Invalid Invoice Number or
details for this transaction","BANK"," ","000000000000",1,1," "," ","
","1.1.1.1",00,"","","","","","","","","","","","","","","0","100","4008",""ÿ
|
JSON Request: |
|
JSON Response: |
|
Below is the Transaction Validation sample Request and Response (For Request data please refer APIs )
Request
HEX String Format |
ASCII Format
|
---|---|
021000099700B9363030312C343239353230333735372C53414C452C3130302C33303030303030303130303030312C31343738322C393339382C3137322C2C2C31364439414639442D394132332D343038462D393732312D3145364534383032433145302C68747470733A2F2F7777772E706C75747573636C6F7564736572766963657561742E696E3A383230312F6170692F436C6F75644261736564496E746567726174696F6E2F56312F506572666F726D54786E56616C69646174696F6E0322
|
— ¹6001,4295203757,SALE,100,30000000100001,14782,9398,172,,,16D9AF9D-9A23-408F-9721-1E6E4802C1E0,https://www.plutuscloudserviceuat.in:8201/api/CloudBasedIntegration/V1/PerformTxnValidation"
|
Response
HEX String Format |
ASCII Format
|
---|---|
0299991997000100DE01363030312C535543434553532C312C545831323334353637382C302C5345512D3531332C535543434553532C504153532C53414C452C32312D30362D323032312031393A33353A323720504D2C34323433313237302C30302C49434943492C313630303030302C3432303733392A2A2A2A2A2A343735302C5445535420434152442C3030303030303030303030303030302C38303031323435382C33332C3136342C4D41455354524F2C434152445F434849502C30322C50494E454C4142532C50494E454C4142532C50494E454C4142532C434C4F5345442C2C2C2C2C037A
|
™™— Þ6001,SUCCESS,1,TX12345678,0,SEQ-513,SUCCESS,PASS,SALE,21-06-2021 19:35:27 PM,42431270,00,ICICI,1600000,420739******4750,TEST CARD,000000000000000,80012458,33,164,MAESTRO,CARD_CHIP,02,PINELABS,PINELABS,PINELABS,CLOSED,,,,,z
|
JSON Request: |
|
JSON Response: |
|
Below is the Sale Complete sample Request and Response (For Request data please refer APIs ).
Request
HEX String Format |
ASCII Format
|
---|---|
0210000997001A363030312C2C2C2C2C2C2C2C2C2C2C03BF
|
— 6001,,,,,,,,,,,
‹
|
Response
HEX String Format |
ASCII Format
|
---|---|
029999199700010221012C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2C2031303030303A317C31303030313A49434943497C31303035303A50696E65206D65726368616E742073746F72657C31303835313A536574746C656D656E74205265706F72747C31303035313A526F68696E69205365632031327C31303930303A42616E67616C6F72657C31303130303A30372F30312F323031357C31303130313A31322D31322D32337C31303135303A3939363534353435343534313835317C31303135313A36353835343137387C31303230303A3030303031307C31303930313A44657461696C73205265706F72747C31303935313A494E564F494345204E554D424552205452414E53414354494F4E2054595045204155544820434F44452043415244204E554D4245522043415244205459504520414D4F554E547C31313030303A31302053414C4520303030303030202A2A2A2A2A2A2A2A2A2A2A2A3238303220564953412052532E313030302E31317C31313030313A534554544C454D454E5420434F4D504C4554457C31313035303A332052533930322E39377C31313035313A302052532E302E30307C31313130303A302052532E302E30307C31313130313A2052533930322E39377C31313135303A302052532E302E30307C31313135313A2052532E302E30307C31313230303A52532E3930322E39372C2C2C2C2049434943492C312C31313135393837342C312C323534322E30302C302C302E30302C2C03B5
|
™™— !,,,,,,,,,,,,,,,,,,,,, ,,,,, 10000:1|10001:ICICI|10050:Pine merchant
store|10851:Settlement Report|10051:Rohini Sec
12|10900:Bangalore|10100:07/01/2015|10101:12-12-23|10150:996545454541851|10151:65854178|10200:000010|10901:Details
Report|10951:INVOICE NUMBER TRANSACTION TYPE AUTH CODE CARD NUMBER CARD
TYPE AMOUNT|11000:10 SALE 000000 ************ 2802 VISA
RS.1000.11|11001:SETTLEMENT COMPLETE|11050:3 RS902.97|11051:0
RS.0.00|11100:0 RS.0.00|11101: RS902.97|11150:0 RS.0.00|11151:
RS.0.00|11200: RS.902.97,,,,,ICICI,1,111598 74,1,2542.00,0 ,0.00,, >>
|
JSON Request: |
|
JSON Response: |
|