Session

Pay at Table integrations are currently standalone from Pay at Counter and Online payments. This is because the current version of the Tables API uses an asynchronous WebSocket protocol for its messaging.

The Session is an abstraction of the length of time an individual customer or party has spent inside the premises. A Session differs from a Table, as every individual or party that enters a restaurant will be assigned a Session, but not necessarily a Table. While a Session generally corresponds to a specific Table, there are instances, like when a party is seated at the bar, where assigning a table is unnecessary.

info

A session can only belong to a single table, and payments are associated with the session - specifically with the sessionId. Multiple sessions can be associated with a single table.

Operations

Because Tables is a WebSockets Async API, each of these session operations has both a SUB (subscribe) as well as a PUB (publish) message. The subscribe messages are requests sent from Dojo to your EPOS, while the publish messages are the response sent from your EPOS to Dojo.

• GetSession retrieves information about a specified session. The session can be either in-progress or finished.
• ListSessions provides detailed information about numerous sessions. Leaving certain parameters empty in the listSessionsRequest will return a list of all sessions.
• LockSession and UnlockSession lock and unlock a session. A session must be locked while payment is in progress, and then it must be unlocked as part of finishing the session, or between each instalment of payment in a split-bill situation.

Schema

Mandatory properties

• id: This uuid is used to uniquely reference each Session.
• createdAt: This is the ISO 8601 UTC date and time of when the session started.
• finishedAt: This is the ISO 8601 UTC formatted date and time of when the session finished.
• isPayable: This property is used to determine whether payments can be taken on a session.
• name: This is a human-readable identifier to describe the session.

Optional properties

• tableName: This is the name of the Table, if the Session is at a table.
• numberOfCovers: This is the party size.
• waiter: This is used for EPOS systems that require additional logic to assign specific areas to particular waiters.

Name

Each session requires a Session.name. When listing all sessions on the card machine, they will be presented in the format of "${Session.tableName} - ${Session.name}". This format enables the use of multiple sessions on a single table, which is useful for supporting EPOS bill splitting functionality. In such cases, we recommend setting the Session.name to reflect the outstanding bill amount for each session. This approach remains effective even when the bill is evenly divided on the EPOS with equal amounts.

Lifecycle

1. A session is created when the party occupies some physical space within the restaurant:

   • The session is assigned a unique UUID upon creation.
   • If the party is seated at a table in the restaurant, the session will be associated with that Table, and that Table marked as TABLE_STATUS_OCCUPIED.
   • The session is currently not payable (not available for payments).
   • The session is not finished.

2. Once the party places their initial order, the session becomes payable as it now has at least one unpaid item. At this point, the billItems object is introduced and added to the session, allowing for updates as more items are included throughout the duration of the session:

   • The session is now payable (available for payments).
   • All items ordered are listed and detailed within the billItems object.

3. The session is finished once the final payment has been taken:

   • The session is now not payable (not available for payments).
   • The session is now finished.
   • If the session is associated with a table, update the table status to TABLE_STATUS_PENDING_AVAILABLE if cleaning is required, or to TABLE_STATUS_AVAILABLE when it is ready for the next party.

Persistence

Although each session is essentially transient, the Tables API necessitates that once a session is marked as finished, it should remain active for a brief time-to-live (TTL). This TTL period should be set to a minimum of one hour before the session can be safely discarded, which allows enough time for any information collection that may be required.