Integrated POS
Introduction
Purpose
This document specifies the design for Integrated POS protocol Interface
The audience for this design specification includes
- Designers
- Developers
- Testers
Scope:
This document covers specifications for the modules involved POS and ERP System protocol interface
Definitions and Acronyms:
STX 0x02 (Start of Data)
ETX 0x03 (End of Data)
FS 0x1C (Field Separator)
References NA
Data Formats
The specification use the following data element formats:
‘a’ : Alphabetic data elements contain a single character per byte.
The permitted characters are alphabetic only (a to z and A to Z, upper and lower case).
‘an’ : Alphanumeric data elements contain a single character per byte. The permitted characters are alphabetic (a to z and A to Z, upper and lower case) and numeric (0 to 9).
‘ans’ : Alphanumeric Special data elements contain a single character per byte.
‘s’ : Special data elements contain a single character per byte.
‘b’ : These data elements consist of unsigned binary numbers.
‘cn’ : Compressed numeric data elements consist of two numeric digits (having values in the range Hex '0'–'9') per byte. These data elements are left justified and padded with trailing hexadecimal 'F's.
‘n’ : Numeric data elements consist of two numeric digits (having values in the range Hex '0' – '9') per byte. These digits are justified and padded with leading hexadecimal zeroes. Other specifications sometimes refer to this data format as Binary Coded Decimal (“BCD”) or unsigned packed.
‘var’ : Variable data elements are variable length and may contain any bit combination. Additional information on the formats of specific variable data elements is available elsewhere.
Design Overview
System Overview
This solution gives the Integrated POS capability to use POS devices for credit/debit card payment transactions.
Hardware Interfaces
The following are the software and hardware requirements for this solution -
Hardware
- POS
- ERP System
- Serial Port Cable (to connect POS with ERP system)
Major Design Constraints and Limitations : None
Communication Settings: COM port is used for Serial Communication between POS and ERP system. The default communication settings for Serial Port
Baud rate 9600 bps. It can go upto 1152000 bps - 8 data bits - No parity - 1 stop bit For
Process Flow
The following are the steps involved to get approval for Credit / Debit transactions using this solution.
- During idle state, POS device listens in the Serial Port
- ERP System checks the availability of POS device by sending CHECKPOS command.
- POS device responds positively for CHECKPOS command.
- ERP System sends the DOTRAN command with all necessary Data.
- POS device validates the received data and Initiate the transaction with bank.
- ERP system waits for Response from POS device.
- If approved, POS device communicates the details to ERP SYSTEM.
Commands
CHKPOS Packet:
Purpose: To check whether POS device is connected to ERP SYSTEM.
Request Packet : <STX>CHKPOS.[status] <ETX>
Packet Length: Maximum: 10 bytes , Minimum: 10 bytes
Request Packet:
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| CHKPOS | ans | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | ans | 2 | ‘00’ – default. |
| <ETX> | s | 1 | End of Text |
Response Packet: <STX>CHKPOS.[status]<ETX>
Packet Length: Maximum: 10 bytes, Minimum: 10 bytes
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| CHKPOS | ans | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | ans | 2 | Status of the transaction. ‘00’ – Success. (Ready for Transaction) ‘01’ – Uninitialized |
| <ETX> | s | 1 | End of Text |
Response Packet Elements:
Request Data Sample: <STX> CHKPOS.00<ETX>
Response Data Sample: <STX> CHKPOS.00<ETX>
Request of DOTRAN Packet for Sale and Balance Enquiry
- Purpose To get transaction details from POS device Packet Length
- Maximum: xx characters
Request Packet Elements :
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | ans | 6 | Packet Type |
| ‘.’ | s | 1 | |
| status | ans | 2 | Status of the transaction. ‘00’ – Success. |
| <FS> | s | 1 | Field Separator |
| TRAN TYPE | N2 | 2 | SALE (00) UPI (19) |
| <FS> | s | 1 | Field Separator |
| LEN | N2 | 2 | Data Length |
| <FS> | s | 1 | Field Separator |
| DATA | Ans | DATA | |
| <FS> | S | 1 | Field Separator |
| TRANS TIME OUT | N2 | 2 | Transaction timeout |
| <FS> | S | 1 | Field Separator |
| SWIPE TIME OUT | N2 | 2 | Swipe time out |
| <FS> | S | 1 | Field Separator |
| <ETX> | s | 1 | End of Text |
- Minimum: xx characters
| Sample Data | Length | Data |
|---|---|---|
| Balance Enquiry | 01 | D.1 |
| Sale | 13 | D.2 |
- 0x31 – Saving Account
- 0x32 – Current Account
- 0x33 – Credit Account Selected
- 0x31 – Saving Account
- 0x32 – Current Account
- 0x33 – Credit Account Selected
Amount (n12)
Example of the DOTRAN Request Packet: <STX>DOTRAN.00<FS>00<FS>13<FS>data<FS><ETX>
| Field | Value |
|---|---|
| <STX>DOTRAN. | 02 44 4F 54 52 41 4E 2E |
| Status | 30 30 |
| <FS>Tran. Type | 1C 00 |
| <FS>Data Length | 1C 00 13 |
| <FS>Account Type | 1C 31 |
| Amount | 00 00 00 10 00 00 |
| <FS> Transaction Time | 1C 01 50 |
| out – 150 seconds | |
| <FS> Swipe Time out | 1C 00 50 |
| 50 seconds | |
| 1C0686 | |
| <FS> JSON Length | |
| UDF | {“merfno”:”7760”, |
| “custName”:”Vijit”,“mobNo”:”123456789” | |
| “udf1”:”400036666”,“udf2”:”Sale”, | |
| “udf3”:”CST No-34/3, village chakra, mumbai”, | |
| “udf4”:”4539”,”udf5”:”47642867”,”udf6”:”ASIX” | |
| “udf7”:”DC”,”udf8”:”AXISP”,”udf9”:”INT”, | |
| “udf10”:”6789***990”,”udf11”:”INT”, | |
| “udf12”:”907891919191”} | |
| Product | {"prodName":"Library", |
| "prodAmount":1000.00, | |
| "prodName":"Tuition", | |
| "prodAmount":2000.00} | |
| <FS><ETX> | 1C 03 |
Response DOTRAN Packet for Sale/Balance Inquiry:
If card not swiped successfully and transaction not started due to some reason than terminal send the response packet as below:
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | Ans6 | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | Ans2 | 2 | Status of the transaction. ‘00’ – if success. ‘01’ – if failed, ‘02’ – Time out to swipe the card, ‘03 ‘--communication failed in start of transaction, ‘04 ‘-- Read Card Error, ‘05’-- Bal inq. Not allowed, ‘06’—communication failed b/w the processing, ‘07’ – Batch Locked, ‘08’ - Uninitialized ‘09’ - Fall Back |
| ETX | s | 1 | End of Packet |
Batch Locked State: Instead of continuing with the SALE transaction system first should send the settlement command as previous settlement request has been failed.
Uninitialized State: Terminal must be initialized first as this populate essential parameter for terminal to operate.
Fallback state: - When inserted EMV card chip malfunction then terminal moves to fallback state to read data through the magstripe for immediate next transaction.
Example of the response packet: <STX>DOTRAN.02<ETX>
| Field | Value |
|---|---|
| <STX>DOTRAN. | 02 44 4F 54 52 41 4E 2E |
| Status | 30 32 |
| <FS><ETX> | 1C 03 |
After completing the transaction, terminal send the data with Transaction Details as:
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | Ans6 | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | Ans2 | 2 | Status of the transaction. ‘00’ – Success. ‘01’ – Fail |
| FS | S | 1 | Field Separator |
| TRAN TYPE | N2 | 2 | SALE (00) BALANCE ENQUIRY (31) |
| FS | S | 1 | Field Separator |
| LEN | BCD | 2 | Data Length |
| <FS> | s | 1 | Field Separator |
| Receipt Hd1 | Ans22 | 22 | Receipt Header 1 |
| <FS> | s | 1 | Field Separator |
| Receipt Hd2 | Ans22 | 22 | Receipt Header 2 |
| <FS> | s | 1 | Field Separator |
| Receipt Hd3 | Ans22 | 22 | Receipt Header 3 |
| <FS> | s | 1 | Field Separator |
| PAN | N4 | 4 | Last 4 digits of PAN |
| <FS> | s | 1 | Field Separator |
| TRAN AMOUNT | N12 | 12 | Transaction Amount |
| <FS> | s | 1 | Field Separator |
| Time | N6 | 6 | Time HHMMSS |
| <FS> | s | 1 | Field Separator |
| Date | N4 | 4 | Date MMYY |
| <FS> | s | 1 | Field Separator |
| RRN | AN12 | 12 | Retrieval Ref. Number |
| <FS> | s | 1 | Field Separator |
| App. Code | AN6 | 6 | Approval Code |
| <FS> | s | 1 | Field Separator |
| Res. Code | AN2 | 2 | Response getting from Host |
| <FS> | s | 1 | Field Separator |
| TID | ANS8 | 8 | Terminal Id |
| <FS> | s | 1 | Field Separator |
| MID | ANS15 | 15 | Merchant Id |
| <FS> | s | 1 | Field Separator |
| INV NO | ANS6 | 6 | Invoice Number |
| <FS> | s | 1 | Field Separator |
| CARD TYPE | ANS10 | 10 | Card Type |
| <FS> | s | 1 | Field Separator |
| BATCN NO | ANS6 | 6 | Batch Number |
| <FS> | s | 1 | Field Separator |
| <ETX> | s | 1 | End of Text |
- Example of the Response Packet Sent to ERP SYSTEM: <STX>DOTRAN.00<FS>00<FS>Rcpt. Hdr1<FS>Rcpt. Hdr2<FS>Rcpt. Hdr3<FS> Pan<FS>Amount<FS>Time<FS>Date<FS>Exp.Date<FS>RRN<FS>App.Code<F S>Resp.code<FS>TID<FS>MID<FS>Invoice no<FS>Card type<FS>Batch no<FS><ETX>
| Field | Value |
|---|---|
| <STX>DOTRAN. | 02 44 4F 54 52 41 4E 2E |
| Status | 30 30 |
| <FS>Tran. Type | 1C 00 |
| <FS>Length | 1C 01 70 |
| 1C 53 48 4F 50 50 45 52 53 42 42 59 49 32 20 20 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr1 1C 43 48 41 4E 44 49 56 49 4C 49 20 20 20 20 20 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr2 1C 4D 55 4D 42 41 49 20 20 20 20 20 20 20 4D 48 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr3 | |
| Last 4 digits of PAN | 1C 21 03 |
| <FS>Amount | 1C 00 00 00 10 00 00 |
| <FS>Time | 1C 12 12 00 |
| <FS>Date | 1C 01 01 |
| <FS>RRN | 1C 32 30 30 37 32 30 30 37 32 30 30 37 |
| <FS>App Code | 1C 31 32 32 33 34 35 |
| <FS>Resp. Code | 1C 30 30 |
| <FS>TID | 1C 33 30 30 30 30 30 30 34 |
| 1C 31 32 33 34 35 36 37 38 39 30 31 32 33 34 35 <FS>MID | |
| <FS>Invoice No | 1C 30 30 30 30 37 35 |
| <FS>Card Type | 1C 56 49 53 41 20 20 20 20 20 20 |
| <FS>Batch No. | 1C 30 30 30 30 38 34 |
| <FS>ETX | 1C 03 |
Request of DOTRAN Packet for Settlement
- Purpose: To settle batch from POS device.
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | ans | 6 | Packet Type |
| ‘.’ | s | 1 | |
| status | ans | 2 | Status of the transaction. ‘00’ – Success. ‘01’ – Fail. |
| <FS> | s | 1 | Field Separator |
| TRAN TYPE | N2 | 2 | SETTLEMENT (92) |
| <FS> | s | 1 | Field Separator |
| LEN | n | 2 | 00 |
| <FS> | s | 1 | Field Separator |
| DATA | Ans | NULL | |
| <FS> | S | 1 | Field Separator |
| <ETX> | s | 1 | End of Text |
- Packet Length : Maximum: xx characters, Minimum: xx characters
Request Packet Elements
- Example of the DOTRAN Request Packet: <STX>DOTRAN.00<FS>92<FS>00<FS><FS><ETX>
Response of DOTRAN for Settlement
Response packet in case settlement fails in between, either due to communication failure or batch is empty.
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | Ans6 | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | Ans2 | 2 | Status of the transaction. ‘00’ – Success, ‘01’ – Batch Empty, ‘02’ – Uninitialized, ’03’-- Communication failed in start of transaction,‘04’-- Failed in b/w processing, ’05’-- Settlement Total NULL |
| ETX | s | 1 | End of Packet |
After completing the transaction, terminal send the data with Transaction Details as:
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | ans | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | ans | 2 | Status of the transaction. ‘00’ – Success, ‘01’ – Fail. |
| FS | S | 1 | Field Separator |
| TRAN TYPE | N2 | 2 | SETTLEMENT (92) |
| FS | S | 1 | Field Separator |
| LEN | BCD | 2 | Data Length |
| <FS> | s | 1 | Field Separator |
| Receipt Hd1 | ans | 22 | Receipt Header 1 |
| <FS> | s | 1 | Field Separator |
| Receipt Hd2 | ans | 22 | Receipt Header 2 |
| <FS> | s | 1 | Field Separator |
| Receipt Hd3 | ans | 22 | Receipt Header 3 |
| <FS> | s | 1 | Field Separator |
| SALE COUNT | N4 | 4 | Number of Sale transaction completed |
| <FS> | S | 1 | Field Separator |
| SALE TOTAL | N12 | 12 | Sale Total |
| <FS> | s | 1 | Field Separator |
| VOID COUNT | N4 | 4 | Number of Void transaction completed |
| <FS> | S | 1 | Field Separator |
| VOID TOTAL | N12 | 12 | VOID Total |
| <FS> | s | 1 | Field Separator |
| Time | N6 | 6 | Time HHMMSS |
| <FS> | s | 1 | Field Separator |
| Date | N6 | 6 | Date YYMMDD |
| <FS> | s | 1 | Field Separator |
| RRN | AN12 | 12 | Retrieval Ref. Number |
| <FS> | s | 1 | Field Separator |
| Resp. Code | AN2 | 2 | Response getting from Host |
| <FS> | s | 1 | Field Separator |
| TID | ANS8 | 8 | Terminal Id |
| <FS> | s | 1 | Field Separator |
| MID | ANS15 | 15 | Merchant Id |
| <FS> | s | 1 | Field Separator |
| INV NO | ANS6 | 6 | Invoice Number |
| <FS> | s | 1 | Field Separator |
| CARD TYPE | ANS10 | 10 | Card Type |
| <FS> | s | 1 | Field Separator |
| BATCN NO | ANS6 | 6 | Batch Number |
| <FS> | s | 1 | Field Separator |
| Host Name | ANS10 | 10 | Host Name |
| <FS> | S | 1 | Field separator |
| <ETX> | s | 1 | End of Text |
Example of the Response Packet Sent to ERP SYSTEM
<STX>DOTRAN.00<FS>92<FS>Rcpt. Hdr1<FS>Rcpt. Hdr2<FS>Rcpt. Hdr3<FS>SALE COUNT<FS>SALE TOTAL<FS>VOID COUNT<FS>VOID TOTAL<FS>Time<FS>Date<FS> Resp.code<FS>TID<FS>MID<FS>Batch no<FS><ETX>
| Field | Value |
|---|---|
| <STX>DOTRAN. | 02 44 4F 54 52 41 4E 2E |
| Status | 30 30 |
| <FS>Tran. Type | 1C 92 |
| <FS>Length | 1C 01 33 |
| 1C 53 48 4F 50 50 45 52 53 42 42 59 49 32 20 20 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr1 1C 43 48 41 4E 44 49 56 49 4C 49 20 20 20 20 20 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr2 1C 4D 55 4D 42 41 49 20 20 20 20 20 20 20 4D 48 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr | |
| <FS>Sale Count | 1C 00 02 |
| <FS>Sale Total | 1C 00 00 00 00 20 00 |
| <FS>Void Count | 1C 00 01 |
| <FS>Void Total | 1C 00 00 00 00 10 00 |
| <FS>Time | 1C 12 12 00 |
| <FS>Date | 1C 01 01 01 |
| <FS>Resp. Code | 1C 35 30 |
| <FS>TID | 1C 33 30 30 30 30 30 30 34 |
| 1C 31 32 33 34 35 36 37 38 39 30 31 32 33 34 35 <FS>MID | |
| <FS>Batch No. | 1C 30 30 30 30 38 34 |
| 1C 03 |
Name Format Length Description
| <STX> | s | 1 | Start of Text |
|---|---|---|---|
| DOTRAN | ans | 6 | Packet Type |
| ‘.’ | s | 1 | |
| status | ans | 2 | Status of the transaction. ‘00’ – Success. |
| <FS> | s | 1 | Field Separator |
| TRAN TYPE | N2 | 2 | VOID (01) |
| <FS> | s | 1 | Field Separator |
| LEN | BCD | 2 | 00 17 |
| <FS> | s | 1 | Field Separator |
| INVOICE NUM | ANS6 | 6 | Invoice Number |
| <FS> | s | 1 | Field Separator |
| BATCH No | ANS6 | 6 | Batch Number |
| <FS> | s | 1 | Field Separator |
| PAN LAST 4 DIGIT | N4 | 4 | Primary Account Number Last 4 Digit |
| <FS> | S | 1 | Field Separator |
| <ETX> | s | 1 | End of Text |
Request of DOTRAN Packet for Void
- Purpose: To get transaction details from POS device.
- Packet Length:
- Maximum: xx characters
- Minimum: xx characters
Request Packet Elements:
Example of the DOTRAN Request Packet
<STX>DOTRAN.00<FS>01<FS>00 17<FS>30 30 30 30 37 35<FS>30 30 30 3038 34<FS>21 03<FS><ETX>
Response of DOTRAN Packet for Void
Response packet in case the void transaction failed in between.
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | Ans6 | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | Ans2 | 2 | Status of the transaction.‘00’ – Success, ‘01’ – Uninitialized, ‘02’ - BATCH Locked, ’03’-- Communication failed in start of transaction, ‘04’-- Failed in b/w processing, ‘05’-- Validation Failed ( ERP SYSTEM), ‘06’-- Transaction record not found, ‘07’ – Already voided |
| ETX | s | 1 | End of Packet |
Response sent by terminal after completing the void transaction.
| Name | Format | Length | Description |
|---|---|---|---|
| <STX> | s | 1 | Start of Text |
| DOTRAN | Ans6 | 6 | Packet Type |
| ‘.’ | s | 1 | |
| Status | Ans2 | 2 | Status of the transaction: ‘00’ – Success, ‘01’ – Fail |
| FS | S | 1 | Field Separator |
| TRAN TYPE | N2 | 2 | VOID (01) |
| FS | S | 1 | Field Separator |
| LEN | BCD | 2 | Data Length |
| <FS> | s | 1 | Field Separator |
| Receipt Hd1 | Ans22 | 22 | Receipt Header 1 |
| <FS> | s | 1 | Field Separator |
| Receipt Hd2 | Ans22 | 22 | Receipt Header 2 |
| <FS> | s | 1 | Field Separator |
| Receipt Hd3 | Ans22 | 22 | Receipt Header 3 |
| <FS> | s | 1 | Field Separator |
| PAN Last 4 digit | N4 | Last 4 digits of PAN | |
| <FS> | s | 1 | Field Separator |
| TRAN AMOUNT | N12 | 12 | Transaction Amount |
| <FS> | s | 1 | Field Separator |
| Time | N6 | 6 | Time HHMMSS |
| <FS> | s | 1 | Field Separator |
| Date | N4 | 4 | Date MMYY |
| <FS> | s | 1 | Field Separator |
| RRN | AN12 | 12 | Retrieval Ref. Number |
| <FS> | s | 1 | Field Separator |
| Res. Code | AN2 | 2 | Response getting from Host |
| <FS> | s | 1 | Field Separator |
| TID | ANS8 | 8 | Terminal Id |
| <FS> | s | 1 | Field Separator |
| MID | ANS15 | 15 | Merchant Id |
| <FS> | s | 1 | Field Separator |
| INV NO | ANS6 | 6 | Invoice Number |
| <FS> | s | 1 | Field Separator |
| CARD TYPE | ANS10 | 10 | Card Type |
| <FS> | s | 1 | Field Separator |
| BATCN NO | ANS6 | 6 | Batch Number |
| <FS> | s | 1 | Field Separator |
| <ETX> | s | 1 | End of Text |
Example of the Response Packet Sent to ERP SYSTEM
<STX>DOTRAN.00<FS>01<FS>Rcpt. Hdr1<FS>Rcpt. Hdr2<FS>Rcpt. Hdr3<FS>
Pan<FS>Amount<FS>Time<FS>Date<FS>Exp.Date<FS>RRN<FS> Resp.code
<FS>TID<FS>MID<FS>Invoice no<FS>Card type<FS>Batch no<FS><ETX>
| Field | Value |
|---|---|
| <STX>DOTRAN. | 02 44 4F 54 52 41 4E 2E |
| Status | 30 30 |
| <FS>Tran. Type | 1C 01 |
| <FS>Length | 1C 01 63 |
| 1C 53 48 4F 50 50 45 52 53 42 42 59 49 32 20 20 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr1 1C 43 48 41 4E 44 49 56 49 4C 49 20 20 20 20 20 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr2 1C 4D 55 4D 42 41 49 20 20 20 20 20 20 20 4D 48 20 20 20 20 20 20 20 | |
| <FS>Receipt Hdr3 | |
| <FS> Last 4 digits of PAN | 1C 21 03 |
| <FS>Amount | 1C 00 00 00 10 00 00 |
| <FS>Time | 1C 12 12 00 |
| <FS>Date | 1C 01 01 |
| <FS>Expiry Date | 1C 10 08 |
| <FS>RRN | 1C 32 30 30 37 32 30 30 37 32 30 30 37 |
| <FS>Resp. Code | 1C 30 30 |
| <FS>TID | 1C 33 30 30 30 30 30 30 34 |
| <FS>MID | 1C 31 32 33 34 35 36 37 38 39 30 31 32 33 34 35 |
| <FS>Invoice No | 1C 30 30 30 30 37 35 |
| <FS>Card Type | 1C 56 49 53 41 20 20 20 20 20 20 |
| <FS>Batch No. | 1C 30 30 30 30 38 34 |
| <FS>ETX | 1C 03 |