SCA Functional Specification

DISPLAY_LEFTPANEL

Last updated: 04-Dec-2024
Download as PDF

This command will direct the device to optionally display text, image, offer data selection, charity donation selection, buttons, and maskable numeric input fields on left panel of the Line Item screen during a payment session, replacing any other display residing on the left panel. SCA will continue to receive new line items and display them during this time.

Device UI Required: Yes

Request Packet
Field Rule Type Minimum Maximum Value(s) Description
FUNCTION_TYPE Required Static value N/A N/A DEVICE Type of function
COMMAND Required Static value N/A N/A DISPLAY_LEFTPANEL Command name
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 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
Top Section
Field Rule Type Minimum Maximum Value(s) Description
LEFTPANEL_TEXT Optional Character 1 50 DEVICE Top section. Message or instructions to display to customer on top of left panel. Example: Ask us about upcoming sales!
LEFTPANEL_IMG_TOP Optional Base64 Encoded Data       Top section. Base64 encoded string (maximum 30,000) to be converted to an image. Displays on top of left panel.
  

Note

In Top section, user needs to send either LEFTPANEL_TEXT or LEFTPANEL_IMG_TOP field.

Middle Section
Field Rule Type Minimum Maximum Value(s) Description
LEFTPANEL_IMG_TOP Optional Base64 Encoded Data       Middle section. Base64 encoded string (maximum 30,000) to be converted to an image. Displays in middle of left panel.

Or Offer Data

  

Note

With respect to the combination of TOP section Image field and Middle section Offer data fields, POS_IP and POS_PORT fields must be specified in Start Session command, and this will return an unsolicited response. Refer to Top Image and Middle Offer Data for the sample request and Unsolicited Response - Top Image and Middle Offer Data for the sample response. Also refer to Display Left Panel - Offers for the screen display example.

Field Rule Type Minimum Maximum Value(s) Description
LEFTPANEL_OFFER_ROW_1 Optional Character 1 22   Left panel offer text row 1 display.
LEFTPANEL_OFFER_ROW_2 Optional Character 1 22   Left panel offer text row 2 display.
LEFTPANEL_OFFER_ROW_3 Optional Character 1 22   Left panel offer text row 3 display.
LEFTPANEL_OFFER_ROW_4 Optional Character 1 22   Left panel offer text row 4 display.
LEFTPANEL_OFFER_ROW_5 Optional Character 1 22   Left panel offer text row 5 display.
LEFTPANEL_OFFER_ROW_6 Optional Character 1 22   Left panel offer text row 6 display.
LEFTPANEL_OFFER_ROW_7 Optional Character 1 22   Left panel offer text row 7 display.
LEFTPANEL_OFFER_ROW_8 Optional Character 1 22   Left panel offer text row 8 display.
LEFTPANEL_OFFER_ROW_9 Optional Character 1 22   Left panel offer text row 9 display.
LEFTPANEL_OFFER_ROW_10 Optional Character 1 22   Left panel offer text row 10 display.

Or Charity Amount Data Capture

  

Note

POS_IP and POS_PORT must be specified in Start Session command. Refer to Display Left Panel - Charity for example.

Field Rule Type Minimum Maximum Value(s) Description
DISPLAY_TEXT1 Optional Character 1 26   Charity amount capture text label 1.
DISPLAY_TEXT2 Optional Character 1 26   Charity amount capture text label 2.
DISPLAY_TEXT3 Optional Character 1 26   Charity amount capture text label 3.
DISPLAY_TEXT4 Optional Character 1 26   Charity amount capture text label 4.
DISPLAY_TEXT5 Optional Character 1 26   Charity amount capture text label 5.
AMOUNT1 Optional Character 1 10   Amount text display 1.
AMOUNT2 Optional Character 1 10   Amount text display 2.
AMOUNT3 Optional Character 1 10   Amount text display 3.
AMOUNT4 Optional Character 1 10   Amount text display 4.
AMOUNT5 Optional Character 1 10   Amount text display 5.
Bottom Section
Field Rule Type Minimum Maximum Value(s) Description
LEFTPANEL_IMG_BOTTOM Optional Base64 Encoded Data       Base64 encoded string (maximum 30,000) to be converted to an image. Displays on bottom of left panel.

Or Numeric Input

  

Note

Refer to Display Left Panel - Numeric Input for example.

Field Rule Type Minimum Maximum Value(s) Description
REQUEST_NUMERIC_INPUT Optional Boolean N/A N/A
  • True
  • False
 TRUE will request SCA to display a numeric input field. NOTE: Two unlabeled buttons (red + green) will display by default.
NUMERIC_INPUT_FORMAT Optional Character 1 19  
N indicates numeric. Allowed literals: /, -, $, , ., #, (, ), %, (Space). Example:
  • $NNN.NN
  • #(NNN)-NNNNNN
NUMERIC_INPUT_MASK Optional List    
  • FALSE - No masking
  • TRUE - Full password entry masking
  • TRAILING - Trailing masking (default)
 Numeric entry to be masked.

Or Display Buttons

  

Note

Refer to Display Left Panel - Numeric Input for example.

Field Rule Type Minimum Maximum Value(s) Description
REQUEST_BTNS Optional List    
  • 0 - No buttons
  • 1 - Display 1 button
  • 2 - Display 1 buttons
 Requesting for displaying buttons. Any other value will display 1 button. This cannot be used with REQUEST_NUMERIC_INPUT. POS_IP and POS_PORT must be specified in START command.
BUTTON_LABEL1 Optional Character 1 15   Label for Button 1. Space dependent on combination of input to left panel. As of this publication, Button 1 is on the right. This is used also with Offer Data or Charity Data Capture.
BUTTON_LABEL2 Optional List 1 15   Space dependent on combination of input to left panel. As of this publication, Button 2 is on the left. This is used also with Offer Data or Charity Data Capture.
Example

Following is an example of request packet

<TRANSACTION>
    <FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
    <COMMAND>DISPLAY_LEFTPANEL</COMMAND>
    <LEFTPANEL_TEXT>Ask us about upcoming sales!</LEFTPANEL_TEXT>
    <COUNTER>1</COUNTER>
    <MAC> … </MAC>
    <MAC_LABEL>REG2</MAC_LABEL>
    </TRANSACTION>

Example - Top Image and Middle Offer Data

<TRANSACTION>
    <FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
    <COMMAND>DISPLAY_LEFTPANEL</COMMAND>
    <LEFTPANEL_IMG_TOP>iVBORw0KGgoAAAANSUhE………. </LEFTPANEL_IMG_TOP>
    <LEFTPANEL_OFFER_ROW_1>Buy 1 Get 1 on Pizzas</LEFTPANEL_OFFER_ROW_1>
    <LEFTPANEL_OFFER_ROW_2>Get 30% Discount</LEFTPANEL_OFFER_ROW_2>
    <LEFTPANEL_OFFER_ROW_3>Pay using Visa Card</LEFTPANEL_OFFER_ROW_3>
    <LEFTPANEL_OFFER_ROW_4>Sunday Special</LEFTPANEL_OFFER_ROW_4>
    <LEFTPANEL_OFFER_ROW_5>Holiday Gift</LEFTPANEL_OFFER_ROW_5>
    <LEFTPANEL_OFFER_ROW_6>Special Snacks</LEFTPANEL_OFFER_ROW_6>
    <LEFTPANEL_OFFER_ROW_7>Offers on Cookies</LEFTPANEL_OFFER_ROW_7>
    <LEFTPANEL_OFFER_ROW_8>Pay using Private Card</LEFTPANEL_OFFER_ROW_8>
    <LEFTPANEL_OFFER_ROW_9>Sleepwell Beds</LEFTPANEL_OFFER_ROW_9>
    <LEFTPANEL_OFFER_ROW_10>Get Pedigrees for Free</LEFTPANEL_OFFER_ROW_10>
    <BUTTON_LABEL1>CANCEL</BUTTON_LABEL1>
    <BUTTON_LABEL2>APPLY</BUTTON_LABEL2>
    </TRANSACTION>
Response Packet
Field Type Value Description
RESPONSE_TEXT Character   Processor response text. Example: Operation SUCCESSFUL
RESULT Character   Commonly TIP MODIFIED or DECLINED or CAPTURED. Example: OK
RESULT_CODE Numeric Expected result code: -1, 59001, 59006 This indicates the result code. Refer to Result/Error Codes for details.
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.
CUST_BUTTON_DATA Character   Represents button selected information. Example: 3
CUST_NUMERIC_DATA Numeric   This field will be sent to POS via unsolicited response, not via primary port. Contains numeric data selected. If Numeric Input is not entered and pressed OK, then another unsolicited response will be sent as “Numeric Data Input Skipped”. Refer to Unsolicited Response to POS (If Numeric Input is not entered) for example below. Example: 1
LEFTPANEL_OFFER_ROW_DATA Numeric   This field will be sent to POS via unsolicited response, not via primary port. Contains offer row data selected. If any of the Offer data is not selected and pressed OK, then another unsolicited response will be sent as “No Offer Selected”. Refer to Unsolicited Response to POS (If Offer Data is not selected) for example below. Example: 2|3|6
AMOUNT_DATA Numeric   This field will be sent to POS via unsolicited response, not via primary port. Contains charity selection. Example: 4
POS_RECON Character   POS reconciliation field echoed back if sent in request. Example: RetailPOS1
COUNTER Numeric   Echoes counter sent in the request. Example: 100
Example

Following is an example of response packet

<RESPONSE>
    <RESPONSE_TEXT>Operation SUCCESSFUL</RESPONSE_TEXT>
    <RESULT>OK</RESULT>
    <RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <COUNTER>59</COUNTER>
    </RESPONSE>

Example - Unsolicited Response to POS IP and Port – Top Image and Middle Offer Data

Message Received: <?xml version="1.0"?>
    <RESPONSE>
    <RESPONSE_TEXT>INPUT FROM OFFER DATA</RESPONSE_TEXT>
    <RESULT>OK</RESULT>
    <RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <LEFTPANEL_OFFER_ROW_DATA>2|3|6</LEFTPANEL_OFFER_ROW_DATA> //If 2, 3 and 6 are selected
    </RESPONSE>

Example - Unsolicited Response to POS (If Offer Data is not selected)

Message Received: <?xml version="1.0"?>
    <RESPONSE>
    <RESPONSE_TEXT>No Offer Selected</RESPONSE_TEXT>
    <RESULT>OK</RESULT>
    <RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    </RESPONSE>

Example - Unsolicited Response to POS (If Numeric Input is not entered)

Message Received: <?xml version="1.0"?>
    <RESPONSE>
    <RESPONSE_TEXT>Numeric Data Input Skipped</RESPONSE_TEXT>
    <RESULT>OK</RESULT>
    <RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    </RESPONSE>
Display Left Panel Sample Categories

Display Left Panel - Charity

Display Screen Sample Request
../../_images/device_cmd_display_lp_charity.png 
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>DISPLAY_LEFTPANEL</COMMAND>
<LEFTPANEL_IMG_TOP> /*some img data*/ </LEFTPANEL_IMG_TOP>
<DISPLAY_TEXT1>DISPLAY_TEXT1</DISPLAY_TEXT1>
<DISPLAY_TEXT2>DISPLAY_TEXT2</DISPLAY_TEXT2>
<DISPLAY_TEXT3>DISPLAY_TEXT3</DISPLAY_TEXT3>
<DISPLAY_TEXT4>DISPLAY_TEXT4</DISPLAY_TEXT4>
<DISPLAY_TEXT5>DISPLAY_TEXT5</DISPLAY_TEXT5>
<AMOUNT1>1.00</AMOUNT1>
<AMOUNT2>2.00</AMOUNT2>
<AMOUNT3>3.00</AMOUNT3>
<AMOUNT4>4.00</AMOUNT4>
<AMOUNT5>5.00</AMOUNT5>
</TRANSACTION>

Display Left Panel - Custom Buttons

Display Screen Sample Request
../../_images/device_cmd_display_lp_custm_buttn.png 
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>DISPLAY_LEFTPANEL</COMMAND>
<LEFTPANEL_TEXT>Ask us about upcoming sales!</LEFTPANEL_TEXT>
<LEFTPANEL_IMG> /*some img data*/ </LEFTPANEL_IMG>
<REQUEST_BTNS>2</REQUEST_BTNS>
<BUTTON_LABEL1>button 1</BUTTON_LABEL1>
<BUTTON_LABEL2>button 2</BUTTON_LABEL2>
</TRANSACTION>

Display Left Panel - Numeric Input

Display Screen Sample Request
../../_images/device_cmd_display_lp_num_input.png 
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>DISPLAY_LEFTPANEL</COMMAND>
<LEFTPANEL_IMG_TOP> /*some img data*/ </LEFTPANEL_IMG_TOP>
<LEFTPANEL_IMG> /*some img data*/ </LEFTPANEL_IMG>
<REQUEST_NUMERIC_INPUT>TRUE</REQUEST_NUMERIC_INPUT>
</TRANSACTION>

Display Left Panel - No User Input

Display Screen Sample Request
../../_images/device_cmd_display_lp_no_usr_input.png 
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>DISPLAY_LEFTPANEL</COMMAND>
<LEFTPANEL_TEXT>Ask us about upcoming sales!</LEFTPANEL_TEXT>
<LEFTPANEL_IMG> /* some img data*/</LEFTPANEL_IMG>
<LEFTPANEL_IMG_BOTTOM> /* some img data*/ </LEFTPANEL_IMG_BOTTOM>
</TRANSACTION>

Display Left Panel - Offers

Display Screen Sample Request
../../_images/device_cmd_display_lp_offers.png 
<TRANSACTION>
<FUNCTION_TYPE>DEVICE</FUNCTION_TYPE>
<COMMAND>DISPLAY_LEFTPANEL</COMMAND>
<LEFTPANEL_IMG_TOP> /*some img data*/ </LEFTPANEL_IMG_TOP>
<LEFTPANEL_OFFER_ROW_1>Buy 1 Get 1 on Pizzas</LEFTPANEL_OFFER_ROW_1>
<LEFTPANEL_OFFER_ROW_2>Get 30% Discount</LEFTPANEL_OFFER_ROW_2>
<LEFTPANEL_OFFER_ROW_3>Pay using Visa Card</LEFTPANEL_OFFER_ROW_3>
<LEFTPANEL_OFFER_ROW_4>Sunday Special</LEFTPANEL_OFFER_ROW_4>
<LEFTPANEL_OFFER_ROW_5>Holiday Gift</LEFTPANEL_OFFER_ROW_5>
<LEFTPANEL_OFFER_ROW_6>Special Snacks</LEFTPANEL_OFFER_ROW_6>
<LEFTPANEL_OFFER_ROW_7>Offers on Cookies</LEFTPANEL_OFFER_ROW_7>
<LEFTPANEL_OFFER_ROW_8>Pay using Private Card</LEFTPANEL_OFFER_ROW_8>
<LEFTPANEL_OFFER_ROW_9>Sleepwell Beds</LEFTPANEL_OFFER_ROW_9>
<LEFTPANEL_OFFER_ROW_10>Get Pedigrees for Free</LEFTPANEL_OFFER_ROW_10>
<BUTTON_LABEL1>CANCEL</BUTTON_LABEL1>
<BUTTON_LABEL2>APPLY</BUTTON_LABEL2>
</TRANSACTION>
Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo