Terminal API Custom User Interface Guide

This document provides a step-by-step guide for merchants who manage POS and ECR systems and use the Terminal API app, and want to display a customized screen on the terminal when certain actions are triggered. This allows information to be shown or input to be collected during defined operational flows. 

The screens are fully customizable and can support a wide range of use cases tailored to customer needs. Think of them as white-label interfaces whose content you can adapt to present information in different ways.

Typical use cases include:

• Confirmations or promotional messages with a title, subtitle, description, and action buttons to capture user decisions.

• Provide a single-choice selection from a list, with optional icons and a unique ID per option (such as ratings, feedback, or receipt delivery preferences)

• Allow multiple selections from a list (checkbox-style) with icons and configurable actions.

• Show a custom image (e.g., promo or branding) with configurable button colors and standard actions.

• Display a QR code for scanning to enroll, access resources, or connect to external services.

• Present structured data in a table or formatted list for receipts, itemized details, or transaction information.

• Capture a digital signature for approvals, contracts, or delivery confirmations.

• Collecting data such as email, phone number, ZIP code, or tip amount with built-in validation.

General Usage

These screens are displayed in response to HTTP requests from an external system (e.g., a Point-of-Sale system, a remote server, ECR, or a tool like Postman). You will not directly "open" these screens from the application's main interface. Instead, they will appear automatically when you send http request to the terminal API with a proper payload body.
Check the api specifications https://docs.terminal.worldline-solutions.com/api-reference#tag/Payments to see all the required payload for all UI screens in the example section. These API specifications are general ones that include the payloads of the payment transactions, and they are compatible with the UI screens as well.

Request and interaction flow

1- The external system sends a POST HTTP request to the terminal api " https://api.terminal.iacc.global.worldline-solutions.com/api/v1/merchants/{umid}/terminals/{utid}/tapi "

2- Include a valid umid and utid with the authorization token

3- The request body must contain a NEXO body as described in the API specifications

4- The NEXO body request consists of SaleToPOIDeviceRequest object that contains Header and DeviceRequest objects

5- The TAPI app will treat the request as a UI request only if an InputRequest object is provided inside DeviceRequest

6- Specify the screen to display by providing DisplayOutput -> MessageContent -> InfoScreen (or any other supported screen name)

7- The application will display the corresponding screen immediately.

8- Your interaction with these screens will involve viewing information, making selections, or entering data as prompted.

9- Once you complete the interaction, the application will send a response back to the external system.

Example of the request

    
    curl --location 'https://api.terminal.iacc.global.worldline-solutions.com/api/v1//merchants/mohamed/terminals/mohamed1/tapi' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer e.....\
--header 'Cookie: AWSALB=h.....' \
--data '{
    "SaleToPOIDeviceRequest": {
        "Header": {
            "MessageFunction": "SDDR",
            "ProtocolVersion": "5.0-WL1.0",
            "ExchangeIdentification": "440",
            "CreationDateTime": "2020-05-04T18:13:51.0+01:00",
            "InitiatingParty": {
                "Identification": "SaleTermA",
                "Type": "MERC"
            }
        },
        "DeviceRequest": {
            "InputRequest": {
                "DisplayOutput": {
                    "MessageContent": {
                        "InfoScreen": {
                            "ShowLogo" : true,
                            "BackgroundColor": "#6200EE",
                            "ButtonColor": "#3700B3",
                            "Title": "Do you want to redeem your loyalty card?",
                            "Subtitle": "You currently have enough point for a 2.50 EUR discount",
                            "PrimaryButton": {
                                "ButtonId": "first_button",
                                "ButtonContent": "Yes"
                            },
                            "SecondaryButton": {
                                "ButtonId": "second_button",
                                "ButtonContent": "No"
                            }
                        }
                    }
                },
                "InputData": {
                    "InputCommand": "GetAnyKey",
                    "MaximumInputTime": "30000"
                }
            }
        }
    }
}'

    

Screen scope

Showing any screen depends on the MessageContent object that the external system sends. MessageContent should contain the screen names like:

• InfoScreen : A basic information display with a title, subtitle, descriptive text, and primary/secondary action buttons. Ideal for confirmations, promotional messages, or scenarios where you need to capture a user’s decision.

• ImageInfoScreen : Shows an image with texts. Excellent for transaction status screens, with customizable button colors and standard actions.

• MultiOptionSingleSelectionScreen : A single-choice interface with multiple options, each supporting custom icons. Great for menus or category selection, each option includes a unique ID for response handling.

• QRScreen : Displays a QR code for easy scanning. Perfect for loyalty enrollments, website links, or linking to external resources, with customizable title/subtitle and optional actions.

• InfoTableScreen : Presents structured data in a table or formatted list. Ideal for receipts, itemized bills, or transaction details, with properly aligned, readable data.

• SignatureScreen : A digital signature capture area for electronic approvals, contracts, or delivery confirmations. Includes a drawing surface and confirm/cancel options.

• ImageScreen : Shows a base64-encoded image only. Excellent for promos, product visuals, instructions, or branding, with customizable button colors and standard actions.

• MultiOptionMultipleSelectionScreen : A multiple-choice interface that allows selecting several options. Useful for surveys, preferences, or configuration tasks, with checkbox-style selection, icons, and customizable action buttons.

• CaptureDataScreen : A data input interface with built-in validation and typed fields (e.g., EMAIL). Suitable for collecting contact information, registration data, or any structured input, with clear labeling and standard submit/cancel actions.

Customization and look

Users can control the screen appearance and which UI elements are shown by including element fields in the request JSON (in MessageContent). The application will render the corresponding screen based on the specified fields.

Not all fields are applicable for every screen, use the relevant fields for the screens that you need. You can find all the relevant fields in  the API specifications .

  Common Fields
  These fields are common across most of the screens:

    ShowLogo : (Optional) a Boolean field to specify whether to show the Worldline logo at the top of the screen.
    Title : (Mandatory) The main heading for the screen.
   * Subtitle : (Optional) Additional information or a sub-heading.

    Text : (Optional) Detailed text explaining the image or providing instructions.
    PrimaryButton : (Optional) The main action button.
        ButtonId : (Mandatory if PrimaryButton is present) A unique identifier for the button.
        ButtonContent : (Mandatory if PrimaryButton is present) The text displayed on the button.
    SecondaryButton : (Optional) The secondary action button.
        ButtonId : (Mandatory if SecondaryButton is present) A unique identifier for the button.
       * ButtonContent : (Mandatory if SecondaryButton is present) The text displayed on the button.

Supported Icon Formats (applies to Icon and OptionIcon only)

• Description: It accepts a string to indicate the type and icon to display. This flow applies only to Icon and OptionIcon fields.

• Formats: You have to provide one of the following three formats

material.iconName : Use the material. prefix; displays the iconName stored in the drawable resources. ( Material Icons )

icon.iconName : Use the icon. imageName; which must be stored in the drawable resource folder in Tapi app (check the available icons in our UI library at the end of this guide)

emoji.emojiUnicode or emoji.EmojiCharacter : Use the emoji. prefix; displays the specified emoji by Unicode or by the actual emoji character. ( Unicode emoji list )

Emulator

You can use this emulator to simulate how the feature works and check how the screens look like. ( link )

Screen Guides