Are you looking for test card numbers?

Would you like to contact support?

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.
    Data elements in JSON format
    {
        "Session": {
            "Id": 12345,
            "Type": "Begin"
        },
        "Operation": [
            {
                "Type": "InputRequest",
                "Variant": "WaitingScreen",
                "UserInterfaceData": {
                    "WaitingScreenTimeoutMs": 15000
                }
            },
            {
                "Type": "DisplayRequest",
                "Variant": "WaitingScreen",
                "UserInterfaceData": {
                    "WaitingScreenTimeoutMs": 10000
                }
            }
        ]
    }

    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.

    Base64 encoded message
    ewogICAgIlNlc3Npb24iOiB7CiAgICAgICAgIklkIjogMTIzNDUsCiAgICAgICAgIlR5cGUiOiAiQmVnaW4iLAogICAgfSwKICAgICJPcGVyYXRpb24iOiBbCiAgICAgICAgewogICAgICAgICAgICAiVHlwZSI6ICJJbnB1dFJlcXVlc3QiLAogICAgICAgICAgICAiVmFyaWFudCI6ICJXYWl0aW5nU2NyZWVuIiwKICAgICAgICAgICAgIlVzZXJJbnRlcmZhY2VEYXRhIjogewogICAgICAgICAgICAgICAgIldhaXRpbmdTY3JlZW5UaW1lb3V0TXMiOiAxNTAwMAogICAgICAgICAgICB9CiAgICAgICAgfSwKICAgICAgICB7CiAgICAgICAgICAgICJUeXBlIjogIkRpc3BsYXlSZXF1ZXN0IiwKICAgICAgICAgICAgIlZhcmlhbnQiOiAiV2FpdGluZ1NjcmVlbiIsCiAgICAgICAgICAgICJVc2VySW50ZXJmYWNlRGF0YSI6IHsKICAgICAgICAgICAgICAgICJXYWl0aW5nU2NyZWVuVGltZW91dE1zIjogMTAwMDAKICAgICAgICAgICAgfQogICAgICAgIH0KICAgIF0KfQ==
  3. Make a POST request to a Terminal API endpoint, specifying:

    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.
    Admin request - start session
    {
       "SaleToPOIRequest": {
          "MessageHeader": {
             "ProtocolVersion": "3.0",
             "MessageClass": "Service",
             "MessageCategory": "Admin",
             "MessageType": "Request",
             "ServiceID": "POSSystemID12345",
             "SaleID": "S00101",
             "POIID": "V400m-324688179"
          },
          "AdminRequest": {
             "ServiceIdentification": "ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkJlZ2luIgogICB9LAogICAiT3BlcmF0aW9uIjpbCiAgICAgIHsKICAgICAgICAgIlR5cGUiOiJJbnB1dFJlcXVlc3QiLAogICAgICAgICAiVmFyaWFudCI6IldhaXRpbmdTY3JlZW4iLAogICAgICAgICAiVXNlckludGVyZmFjZURhdGEiOnsKICAgICAgICAgICAgIldhaXRpbmdTY3JlZW5UaW1lb3V0TXMiOjE1MDAwCiAgICAgICAgIH0KICAgICAgfQogICBdCn0="
           }
       }
    }
  4. The AdminResponse shows Response.Result Success.

    Admin request - response
    {
        "SaleToPOIResponse": {
            "AdminResponse": {
                "Response": {
                    "Result": "Success"
                }
            },
            "MessageHeader": {
                "MessageCategory": "Admin",
                "MessageClass": "Service",
                "MessageType": "Response",
                "POIID": "V400m-324688179",
                "ProtocolVersion": "3.0",
                "SaleID": "POSSystemID12345",
                "ServiceID": "S00101"
            }
        }
    }

    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.
    Data elements in JSON format
    {
        "Session": {
            "Id": 12345,
            "Type": "End"
        }
    }
  2. Encode the JSON object to Base64.

    Base64 encoded message
    ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkVuZCIKICAgfQp9
  3. Make a POST request to a Terminal API endpoint, specifying:

    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.
    Admin request - end session
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"Admin",
             "MessageType":"Request",
             "ServiceID":"S00101",
             "SaleID":"POSSystemID12345",
             "POIID":"V400m-324688179"
          },
          "AdminRequest":{
             "ServiceIdentification": "ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkVuZCIKICAgfQp9"
           }
       }
    }
  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 input requests.

See also