ADD
Last updated: 07-Apr-2025
This command adds a line item to the payment transaction and displays line items on the device where possible. Line items can be added when on any screen.
- LINE_ITEM_IDs must be declared in the transaction before they can be referenced (e.g., an offer cannot reference merchandise that is below it in the message).
- Refer to Displaying Line-Item Fields on Device table for details on request fields which are displayed on the device.
Note
Device UI Required: Yes
Request Packet
| Field | Rule | Type | Minimum | Maximum | Value(s) | Description |
|---|---|---|---|---|---|---|
| FUNCTION_TYPE | Required | Static value | N/A | N/A | LINE_ITEM | Type of function |
| COMMAND | Required | Static value | N/A | N/A | ADD | Command name |
| RUNNING_SUB_TOTAL | Optional | Floating point number | 1(2) | 6(2) | Running subtotal. This field supports negative amounts. NOTE: If this tag is not sent in the request, subtotal will not be shown on the screen/terminal – it will be erased if it was shown for the previous Line Item request. Example: 1.00 | |
| RUNNING_TAX_AMOUNT | Required | Floating point number | 1(2) | 6(2) | Running tax total of the transaction. This field supports negative amounts. Example: 0.07 | |
| RUNNING_TRANS_AMOUNT | Required | Floating point number | 1(2) | 6(2) | Running total of the transaction. This field supports negative amounts. Example: 1.07 | |
| RUNNING_DISCOUNT_AMOUNT | Required | Floating point number | 1(2) | 6(2) | Discount amount. Example: -999999.99 | |
| LINE_ITEMS | Optional | List | N/A | N/A |
|
Line items details. Refer to MERCHANDISE Child Elements and OFFER Child Elements sections below for list of child elements. |
| POS_RECON | Optional | Character | 1 | 30 | POS reconciliation. POS Reconciliation field to be echoed back in response to POS. Example: RetailPOS1 | |
| COUNTER | Required | Numeric | 1 | 10 | COUNTER is used for a given MAC label. Each COUNTER should be higher than the last one. This is sed to authenticate the POS. Example: 100 | |
| MAC | Required | Base64 Encoded Data | N/A | N/A | Message Authentication Code. This is used to authenticate the POS. | |
| MAC_LABEL | Required | Character | 1 | 50 | Associated label that tells the device which MAC_KEY to use to decrypt the value of MAC. This is used to authenticate the POS. Example: REG1 |
MERCHANDISE Child Elements
Note
Adds merchandise to the transaction. Displayed on screen or printed on receipt, as supported by device type.
| Field | Rule | Type | Minimum | Maximum | Value(s) | Description |
|---|---|---|---|---|---|---|
| LINE_ITEM_ID | Required | Numeric | 1 | 10 | Line item identifier supplied by the POS. This must be unique to the payment transaction. Example: 1 | |
| SKU | Optional | Character | 1 | 50 | Optional MERCHANDISE element. Example: V4C3D5R2 | |
| UPC | Optional | Character | 1 | 50 | Optional MERCHANDISE element. Example: 521675964352 | |
| DESCRIPTION | Optional | Character | 1 | 17 or 40 |
|
|
| QUANTITY | Optional | Numeric | 1 | 10 | Number of items. The quantity area will be blank for this line item if QUANTITY is not sent. Example: 2 | |
| UNIT_PRICE | Optional | Floating point number | 1(2) | 6(2) | Single item price without tax. This field supports negative amounts. Example: 0.50. NOTE: This field is not applicable to Neo devices (VOS3). Neo device does not have any column for unit price in Line Item screen. | |
| EXTENDED_PRICE | Optional | Floating point number | 1(2) | 6(2) | Price of the entire quantity of this line item (Qty x Unit Price). This field supports negative amounts. The extended price area will be blank for this line item if EXTENDED_PRICE is not sent. Example: 1.00 | |
| FONT_COL_VALUE | Optional | Character | 6 | 6 |
|
OFFER Child Elements
Note
Adds coupons/ discounts to merchandise.
| Field | Rule | Type | Minimum | Maximum | Value(s) | Description |
|---|---|---|---|---|---|---|
| TYPE | Required | List |
|
This indicates the type of offer being applied. | ||
| LINE_ITEM_ID | Required | Numeric | 1 | 10 | Line item identifier supplied by the POS. This must be unique to the payment transaction. Example: 1 | |
| SKU | Optional | Character | 1 | 50 | Optional OFFER element. Example: V4C3D5R2 | |
| DESCRIPTION | Required | Character | 1 | 17 | OFF Text description of offer. Example: 10% | |
| OFFER_AMOUNT | Required | Floating point number | 1(2) | 6(2) | Amount to subtract from the transaction. Example: 0.10 | |
| OFFER_LINE_ITEM | Optional | Numeric | 1 | 10 | Line Item ID to which this is applied. Example: 1 | |
| FONT_COL_VALUE | Optional | Character | 6 | 6 |
|
Example
Following is an example of request packet
<TRANSACTION>
<FUNCTION_TYPE>LINE_ITEM</FUNCTION_TYPE>
<COMMAND>ADD</COMMAND>
<COUNTER>1</COUNTER>
<MAC> … </MAC>
<MAC_LABEL>REG2</MAC_LABEL>
<RUNNING_DISCOUNT_AMOUNT>999999.99</RUNNING_DISCOUNT_AMOUNT>
<RUNNING_SUB_TOTAL>999999.99</RUNNING_SUB_TOTAL>
<RUNNING_TAX_AMOUNT>999999.99</RUNNING_TAX_AMOUNT>
<RUNNING_TRANS_AMOUNT>999999.99</RUNNING_TRANS_AMOUNT>
<LINE_ITEMS>
<MERCHANDISE>
<UNIT_PRICE>5.00</UNIT_PRICE>
<DESCRIPTION>#1 Combo Meal</DESCRIPTION>
<LINE_ITEM_ID>1695155651</LINE_ITEM_ID>
<EXTENDED_PRICE>5.00</EXTENDED_PRICE>
<QUANTITY>1</QUANTITY>
</MERCHANDISE>
<MERCHANDISE>
<UNIT_PRICE>5.00</UNIT_PRICE>
<DESCRIPTION>#1 Combo Meal</DESCRIPTION>
<LINE_ITEM_ID>1695155652</LINE_ITEM_ID>
<EXTENDED_PRICE>5.00</EXTENDED_PRICE>
<QUANTITY>1</QUANTITY>
</MERCHANDISE>
<OFFER>
<TYPE>OTHER_COUPON</TYPE>
<LINE_ITEM_ID>1695155653</LINE_ITEM_ID>
<DESCRIPTION>EmpDisc</DESCRIPTION>
<OFFER_AMOUNT>2.00</OFFER_AMOUNT>
<OFFER_LINE_ITEM>1695155651</OFFER_LINE_ITEM>
</OFFER>
<OFFER>
<TYPE>MERCHANT_COUPON</TYPE>
<LINE_ITEM_ID>1695155654</LINE_ITEM_ID>
<DESCRIPTION>1OffAnyPurch</DESCRIPTION>
<OFFER_AMOUNT>1.00</OFFER_AMOUNT>
<OFFER_LINE_ITEM>1695155651</OFFER_LINE_ITEM>
</OFFER>
</LINE_ITEMS>
</TRANSACTION>
Displaying Line-Item Fields on Device
| Field Name | Display on Device |
|---|---|
| RUNNING_SUB_TOTAL | Yes |
| RUNNING_TAX_AMOUNT | Yes |
| RUNNING_TRANS_AMOUNT | Yes - Displays as Total |
| RUNNING_DISCOUNT_AMOUNT | Yes - Displays as Discount |
| LINE_ITEMS - MERCHANDISE |
|
| LINE_ITEMS - OFFER(s) |
|
Response Packet
| Field | Type | Value | Description |
|---|---|---|---|
| RESPONSE_TEXT | Character | Processor response text. Example: Added line items. | |
| RESULT | Character | This indicates the Result details. Example: OK | |
| RESULT_CODE | Numeric | Expected result codes: -1, 59004, 59040, 59042, 59044, 59045, 59046, 59047, 59048, 59028 | This indicates the result code. |
| TERMINATION_STATUS | Character | SUCCESS or FAILURE | This indicates the transaction termination status. This is the overall status of the transaction irrespective of approved or declined. Like, if the output is generated then the status is SUCCESS and if no output is generated then the status will be FAILURE. |
| POS_RECON | Character | POS reconciliation field echoed back if sent in request. Example: RetailPOS1 | |
| COUNTER | Numeric | Echoes COUNTER sent in the request. Example: 100 |
Transaction Performance Metric
Note
These fields are returned, if SCAPERFMETRIC parameter (Application Parameters) is enabled.
| Field | Type | Value | Description |
|---|---|---|---|
| UI_TIME | Time | This indicates the time duration, for which the device screen is displayed (like error message, prompt screen, remove card screen) till any user action is performed in the command execution flow. This field is not applicable to capture the time for the Processing, Authorizing and transaction status screen. The format of the returned value would be S.sss, where S is seconds (this can be 0 to any positive integer) and sss is milliseconds. In case of any insignificant time or 0.000 value, will not be returned in the response. Example: <UI_TIME>44.028</UI_TIME> |
|
| HOST_TIME | Time | This indicates the time taken for the Connection to the host, sending request and receives data from the host. This field also take the cumulative time for multiple requests which may sent to the host during the transaction including two legged transactions, timeout requests, Auto Last Tran requests, DCC, Credit app proxy. The format of the returned value would be S.sss, where S is seconds (this can be 0 to any positive integer) and sss is milliseconds. In case of any insignificant time or 0.000 value, will not be returned in the response. Example: <HOST_TIME>1.389</HOST_TIME> |
|
| CMD_TIME | Time | This field indicates the total amount of time for a command, which is executed by the application from request received to the response sent. The format of the returned value would be S.sss, where S is seconds (this can be 0 to any positive integer) and sss is milliseconds. In case of any insignificant time or 0.000 value, will not be returned in the response. Example: <CMD_TIME>70.765</CMD_TIME> |
Example
Following is an example of response packet
<RESPONSE>
<RESPONSE_TEXT>Added line items</RESPONSE_TEXT>
<RESULT>OK</RESULT>
<RESULT_CODE>-1</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<COUNTER>1</COUNTER>
</RESPONSE>
Rate this article:
