Point-of-sale icon

Create a session

Create a session that spans multiple requests.

You can make an admin request to create a session that spans multiple requests, including input, display, and payment requests. When you start the session, the terminal shows the waiting screen after every input, display, and payment request until you end the session. This solves the issue that customers may think something is wrong if they provide input and then don't see anything happening on the terminal. The waiting screen is shown for a set amount of time, or until the next request is sent to the terminal.

This is useful for payment flows where someone needs to interact with a terminal, like Pay at Table. It shows that the POS system is not unresponsive, it is just busy doing something that takes a bit of time.

How it works

You need to send two separate admin requests to mark the start and the end of a session. All requests in between belong to a single session.

To include multiple requests in one session:

  1. Before you send the first request, send an admin request to start the session.

  2. Send multiple requests, including input, display, and payment requests.
    When you send an input request, after the user provides input on the terminal, the waiting screen shows for the set amount of time. With display and payment requests, after showing your data on the screen, the waiting screen shows. If you send another request before the waiting screen expires, the waiting screen disappears.

    WaitingScreen

  3. After the last request, send an admin request to end the session.

Step 1: Start the session

  1. Create a JSON object with the following data elements:

    Parameter Required Description
    Session -white_check_mark- An object with:
    • ID: the unique reference of the session.
    • Type: set the value to Begin to start the session.
    Operation -white_check_mark- An object with:
    • Type: the type of request after which the waiting screen shows: InputRequest, DisplayRequest, and Payment .
    • Variant: WaitingScreen.
    • UserInterfaceData.WaitingScreenTimeoutMs: how long the waiting screen is shown on the terminal display, in milliseconds.

    For now, the Operation.Variant can only have WaitingScreen as value. This shows the waiting screen animation on the terminal after every request until you end the session.

  2. Encode the JSON object to Base64.

  3. Make a POST request to a Terminal API endpoint, specifying:

    Parameter Required Description
    ProtocolVersion -white_check_mark- 3.0
    MessageClass -white_check_mark- Service
    MessageCategory -white_check_mark- Admin
    MessageType -white_check_mark- Request
    ServiceID -white_check_mark- Your unique ID for this request.
    SaleID -white_check_mark- Your unique ID for the system where you send this request from.
    POIID -white_check_mark- The unique ID of the terminal that you send this request to.
    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.

  4. The AdminResponse shows Response.Result Success.

    For more information on the Terminal API request structure, see the Terminal API fundamentals.

Step 2: Send requests

  1. Start sending the requests that you specified in the operation.type, including input, display, and payment requests.
  2. After every request sent, the screen shows the waiting screen for the amount of time specified in milliseconds in UserInterfaceData.WaitingScreenTimeoutMs.
  3. Every new request interrupts the waiting screen.

Step 3: End the session

  1. Create a JSON object with the following data elements:

    Parameter Required Description
    ServiceIdentification.Session -white_check_mark- An object with:
    • Id: the unique reference of the session. This must be the same Id as in the start session AdminRequest).
    • Type: set the value to End.

  2. Encode the JSON object to Base64.

  3. Make a POST request to a Terminal API endpoint, specifying:

    Parameter Required Description
    MessageClass -white_check_mark- Service
    MessageCategory -white_check_mark- Admin
    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.

  4. The AdminResponse shows Response.Result Success, same as in Step 1.

You can send an admin request to end the session while the waiting screen is still on the display. This does not interrupt the waiting screen like other requests.
After the session ends, the waiting screen no longer shows after sent input, display, or payment requests.

See also