PowerEPOS "Order N Pay" Overview
The PowerEPOS "Order N Pay" interface is an API/Service for allowing third parties to interface with the PowerEPOS onsite POS system. An example would be a 3rd party integration needing to submit orders and payments directly into the PowerEPOS frontend system. (such as a staff ordering app)
Vocabulary
Before proceeding it will be good to familiarise yourself with the vocabulary used by this API
- Service Mode - A service mode represents an area of service in the outlet. eg Tables, Tabs, Takeaways etc
- Service Mode Entity ID - This refers to the ID related to the service mode. For example, the table number in a Tables service mode, or the takeaway number in a takeaway service mode.
- Adjustment - Adjustment is a term used to collectively refer to either a discount or surcharge in the PowerEPOS system.
- Outlet - Represents a single outlet/venue/store within an organisation
"Order N Pay" Websocket Integration (for cloud based 3rd party integrators)
Overview
This section is targeted at 3rd party integrators who want to be able to communicate directly with the onsite POS system in real time to submit sales and/or payments.
Websocket Server
Since the POS frontend resides on site, connecting to it from an external source can be difficult due to on premise IP, router and/or firewall constraints. As such this interface is designed so that the 3rd party integrator acts as the host, the on site POS system will maintain a websocket connection to the 3rd party system.
This means that the 3rd party integrator must implement a compatible Websocket Server that the POS system can connect to and that also conforms to the specified Authentication and API requirements of the POS.
The base host Uri would be something like wss://websocket.provider.com
Authentication
Integration Notes The websocket server should implement the below codes for disconnection
- (Code: 1000): General disconnection. No specific reason. Client can try to connect again later.
- (Code: 1001): Another client using the same credentials connected, and we only allow one at a time. You should probably not retry connection.
- (Code: 1002): Authentication failure. Your token is not present or invalid.
IMPORTANT: In the event that mutliple connections are detected from the same outlet (ie with same access token), the websocket server must forcefully disconnect the oldest connection with a close code of 1001.
- This can occur during some network failures whereby the POS may reconnect while the server still incorrectly thinks an old connection is active.
- This can occur due to misconfiguration (typically in demo systems) where multiple demo systems may be trying to use the same demo connection. Implementing the correct disconnection codes will ensure that the POS system does not spam the websocket server with reconnection attempts while conflicting with another system.
The POS supports the 3rd party integration performing the following actions via the websocket connection
- GetUserFromPIN: allows the 3rd party to valiate a POS user PIN. The user name and id will be returned for successful requests.
- GetOpenOrders: allows the 3rd party to query the POS for a summary of currently open orders (and their unique ids) in the system.
- GetOrder: allows the 3rd party to query the POS for detailed information about a specific order (by its unique id).
- CreatePayment: allows the 3rd party to submit a payment to an existing open order. This would be used in a scenario where an existing POS order is being paid by the 3rd party system.
- CrateOrder: allows the 3rd party to submit a new sales order to the POS system. This order can include payments if it is being sent as a fully paid order. If no payments are present (or only partial payments), the order will remain open on the POS system until it is paid or updated at a later point in time.
- UpdateOrder: allows the 3rd party to submit additional sale items to an existing order
- SimulatorOrder: allows the 3rd party to submit an order for the POS to "simulate" and return the simulated version (with any automated POS adjustments (eg discounts/surcharges) and/or service charges applied). This then allows the 3rd party to perform an fully paid CreateOrder call while still including any of the POS's standard automated adjustments/service charges.
All websocket messages must be wrapped in a OrderNPayWebsocketRequest model. This model lets the integrator specify the action they are performing and provide the appropriate payload for the message type. The POS system will respond to all websocket requests with the OrderNPayWebsocketResponse model. The POS will provide the appropriate payload for the message type.