menu
Return to solutions

What's on this page

Payment Features / Show Free Text On The Terminal Screen - Android SDK

Intro

This functionality lets the POS show up to 4 lines of free text on the terminal screen at different stages of the transaction. Each line can be up to 17 characters long. It can only be used for OPI-NL with Card Validation, Card Detection, Card Payment or Card PreAuthorisation in combination with APASPP. For Paygear, only Card Detection supports this functionality.

The terminal decides the font, font size and font color of the free text. The text is always centered.

How to send free text

To send free text, add a list of TerminalDisplayText objects to the ExternalTerminal through terminalDisplayText. Each TerminalDisplayText needs:

  • a TerminalDisplayTextWindow, which sets when the text is shown
  • a list of display lines, which holds the text to show

The following code snippet is an example of how to supply custom text for a vending machine that delivers a drink. SCREEN_AT_DELIVERY_BOX is shown while the drink is being prepared, not when it is done.


    TerminalApi terminalService = new TerminalService();
    ExternalTerminal terminal = ExternalTerminal.builder()
            .ipAddress("127.0.0.1")
            .port(4100)
            .compatibilityPort(4102)
            .workstationId("MY WORKSTATION")
            .socketMode(ExternalTerminal.SocketMode.DUAL_SOCKET)
            .terminalType(ExternalTerminal.TerminalType.OPI_NL)
            .terminalDisplayText(Arrays.asList(
                    new TerminalDisplayText(
                            TerminalDisplayTextWindow.SCREEN_WAIT_FOR_CARD,
                            Arrays.asList("Hold your card", "to the reader", "to start your", "drink order")),
                    new TerminalDisplayText(
                            TerminalDisplayTextWindow.SCREEN_AT_WAIT_FOR_FOLLOW_UP,
                            Arrays.asList("Checking your", "card...")),
                    new TerminalDisplayText(
                            TerminalDisplayTextWindow.SCREEN_AT_DELIVERY_BOX,
                            Arrays.asList("Preparing your", "drink...", "Please wait"))))
            .build();

    TerminalDelegate terminalDelegate = new TerminalDelegate() {
    ...
    };

    terminalService.cardDetection(terminal, CardDetectionRequest.builder().requestId("123456789").tokenPurpose(TokenPurpose.TRACKING).build(), terminalDelegate);

TerminalDisplayTextWindow

The TerminalDisplayTextWindow sets when during the transaction the POS text is shown. The possible values are:

TerminalDisplayTextWindow Description
SCREEN_WAIT_FOR_CARD The text is shown while the cardholder is asked to present their card.
SCREEN_AT_WAIT_FOR_FOLLOW_UP The text is shown while the terminal is in the WaitForFollowUp state. This state only exists during a Card Detection, so you can only use this value with a Card Detection.
SCREEN_AT_DELIVERY_BOX The text is shown while the terminal waits for the POS to confirm that the deliveryBox was successful. If the terminal never enters the deliveryBox flow, the text is ignored.

Display lines

Each entry in the list of display lines is one line of text on the terminal screen.

  • The terminal can show at most 4 lines.
  • Each line can be at most 17 characters long.
  • Add a separate entry for each line.
  • For an empty line, use a single space (" ").