Create a flow

Create a session that spans multiple requests.

You can create a flow that spans multiple requests, including input, display, and payment requests. To do so, you send an admin request to start a 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:

Before you send the first request, send an admin request to start the session.
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.
After the last request, send an admin request to end the session.

Step 1: Start the session

Create a JSON object with the following data elements:

Parameter	Required	Description
`Session`		An object with: `ID`: the unique reference of the session. `Type`: set the value to Begin to start the session.
`Operation`		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.

Encode the JSON object to Base64.

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

MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Service
`MessageCategory`		Admin
`MessageType`		Request
`ServiceID`		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used.
`SaleID`		Your unique ID for the POS system component to send this request from.
`POIID`		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

AdminRequest: the request body. This must include:
- ServiceIdentification: the Base64-encoded JSON object.

The AdminResponse shows Response.Result Success.

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

Step 2: Send requests

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

Step 3: End the session