ADD
Last updated: 04-Dec-2024
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. |
| 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. |
| COUNTER | Numeric | Echoes COUNTER sent in the request. Example: 100 |
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:
