Skip to main content

Flows

info

The capabilities mentioned on this page must be registered with the EPOS Capabilities API prior to initiating a Pay At Table flow, learn more here.

The following diagram demonstrates how the Pay at Table product will interact with Dojo and the POS system for settling a table:

Step 1: List orders via SearchOrders​

The initial step in the Pay at Table flow involes the waiter opening the "Integration" screen on the payment device, if configured (on the device) the waiter will be asked to input their waiter id which will be included in the SearchOrders request to the POS system.

The orders returned via the SearchOrders request are then presented on the payment device in a list for the waiter to select from, the name presented on the device for each order is determined by the following logic (first condition to match):

  • displayName field if populated in the Order
  • tableId field if populated in the Order
  • The mandatory id field of the Order
  • Otherwise the id field of an Order is used

Exceptions

  • In cases where the names of orders to be presented on the payment device have duplicates a suffix of "- $number" will be added to the name e.g. Table1 - 1.
  • Dojo payment devices have a 24-character limit for order names. Names longer than this limit will be truncated. Note:

We will only request payable orders by setting the payableOnly parameter to true. Therefore only orders which can be paid for will be presented on the payment device, allowing some orders to be hidden if they're being edited on the POS or have already been fully paid off.

Step 2: Get a specific order to pay via GetOrderById​

The next step in the Pay at Table flow is triggered when a waiter selects an Order from the list of orders (from the previous step), at this point the latest and full state of the order is fetched from the POS system using the id field.

This step ensures that the most recent version of the order is presented on the payment screen before any payment is taken.

Step 3: Takes payment, payment event sent via HandleEvent:payment_intent.status_updated​

The waiter can now take the payments for this order, and depending on how the customer chooses to pay, there may be a single payment or multiple for the order (split payment or pay by items). As part of the payment process, a payment intent is created for each payment and the POS is notified of status changes for each one individually. If a waiter ID was provided on the payment device, an entry with the key waiterId will be included in the metadata on those created payment intents.

The data included in the HandleEvent:payment_intent.status_updated request follows the same structure as the equivalent event in Dojo API Webhooks. In order to get the full information for a payment, the POS system will need to lookup the payment intent via the Dojo API.

To determine which order on the POS system a payment intent belongs to, the POS system should look at the orderDetails.externalId field on the payment intent. This field will be set to the id field from the order returned by the POS in the previous steps.

The POS should wait for the payment intent status to update to Captured before considering the payment final and able to be deducted from the amount to pay on the order.

Note: Events are delivered with an At least once guarantee, so the POS will need to handle receiving duplicate events for the same payment intent.

Step 4: POS submits OrderUpdatedEvent to Dojo​

The final step in the Pay at Table flow requires the POS system to notify Dojo about the update(s) to the order (due to payment(s) in this case) via the submit event endpoint in the Dojo API. This allows Dojo to keep track of order state in realtime without the need for polling.

Last updated on