Lock 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.

To prevent accounting discrepancies between payment devices and your EPOS system, it is essential that payments for any given session are processed sequentially, rather than in parallel. To achieve this, the Tables API requires you to lock a session before initiating any payment. The session should be unlocked after each RecordPayment call.

Lock session

SUB /ListSessions

You must lock the session before processing any payment on the EPOS. If you attempt to pay for a session that isn't locked, the EPOS will issue an Error Response with the code SESSION_NOT_LOCKED.

1. Receive a lockSessionRequest from Dojo.
2. If the specified session does not exist, the EPOS should respond with an Error response with the code SESSION_NO_SUCH_SESSION.
3. Otherwise, if the session exists AND is already locked, the EPOS should respond with an Error response with the code SESSION_ALREADY_LOCKED.
4. Otherwise, if the session exists AND is not already locked, the EPOS should respond with a LockSession response.

{
  "jsonrpc": "2.0",
  "id": "fd8af62f-f685-4e13-925b-453d63553a48",
  "method": "LockSession",
  "params": {
    "sessionId": "6c133121-8423-48af-b9c1-ce6741f224da",
    "requestorInfo": {
      "requestorType": "REQUESTOR_TYPE_CARD_MACHINE",
      "cardMachineRequestorInfo": {
        "terminalId": "123123",
        "waiterId": 1
      }
    }
  }
}

PUB /LockSession

A lockSessionResponse contains a full billItems schema object. This is a snapshot of the session's bill, and it contains a list of all ordered items and the total and outstanding balances.

Expand to see an example of a lock session JSON response body

{
  "jsonrpc": "2.0",
  "id": "fd8af62f-f685-4e13-925b-453d63553a48",
  "result": {
    "billItems": {
      "totalAmount": 950,
      "paidAmount": 100,
      "taxAmount": 190,
      "currency": "GBP",
      "items": [
        {
          "id": "123456789",
          "name": "Classic Burger",
          "category": [
            "mains",
            "burgers"
          ],
          "quantity": 1,
          "amountPerItem": 1000,
          "lastOrderedAt": "2021-01-01T15:00:00.123+02:00",
          "modifiers": [
            {
              "id": "mod-987654321",
              "name": "Extra Cheddar Cheese",
              "amountPerModifier": 100,
              "quantity": 3
            }
          ]
        },
        {
          "id": "987654321",
          "name": "Peroni",
          "category": [
            "drinks",
            "beer",
            "lager"
          ],
          "quantity": 1,
          "amountPerItem": 450,
          "lastOrderedAt": "2021-01-01T15:00:00.123+02:00"
        },
        {
          "id": "987654321",
          "name": "Peroni",
          "category": [
            "drinks",
            "beer",
            "lager"
          ],
          "quantity": 1,
          "amountPerItem": 0,
          "lastOrderedAt": "2021-01-01T15:00:00.123+02:00",
          "modifiers": [
            {
              "id": "mod-123123",
              "name": "Buy 1 get 1 free!",
              "amountPerModifier": -450,
              "quantity": 1
            }
          ]
        },
        {
          "id": "00000001",
          "name": "£5 Voucher",
          "category": [
            "discounts",
            "vouchers"
          ],
          "quantity": 1,
          "amountPerItem": -500,
          "lastOrderedAt": "2021-01-01T15:00:00.123+02:00"
        }
      ],
      "sessionId": "6c133121-8423-48af-b9c1-ce6741f224da"
    }
  }
}

Unlock session

SUB /UnlockSession

The EPOS system must first verify that the session exists, and also that it is currently in a locked state. If a request is made to unlock a session that has already been unlocked, the EPOS system should issue an Error Response with the code SESSION_NOT_LOCKED.

1. Receive an unlockSessionRequest from Dojo.
2. If the specified session does not exist, the EPOS should respond with an Error response with the code SESSION_NO_SUCH_SESSION.
3. Otherwise, if the specified session exists AND is not locked, the EPOS should respond with an Error response with the code SESSION_NOT_LOCKED.
4. Otherwise, if the session exists AND is locked AND fails to unlocked successfully, the EPOS should respond with an Error response with the code SESSION_UNABLE_TO_UNLOCK.
5. Otherwise, if the session exists AND is locked AND is unlocked successfully, the EPOS should respond with an unlockSessionResponse.

{
  "jsonrpc": "2.0",
  "id": "53ce5a20-f9da-4c09-b9e3-053496306d92",
  "method": "UnlockSession",
  "params": {
    "sessionId": "6c133121-8423-48af-b9c1-ce6741f224da",
    "requestorInfo": {
      "requestorType": "REQUESTOR_TYPE_CARD_MACHINE",
      "cardMachineRequestorInfo": {
        "terminalId": "123123",
        "waiterId": 1
      }
    }
  }
}

PUB /UnlockSession

The unlockSessionResponse should contain an empty result to confirm a successful unlock.

{
  "jsonrpc": "2.0",
  "id": "aa276ffe-f55b-4b63-997f-5e6562d3864a",
  "result": {}
}