# Dojo EPOS Integration Documentation

> The EPOS Data API defines the contract that external POS/EPOS systems implement so that Dojo products can register capabilities, send and receive events, and coordinate shared commerce entities. Includes the WebSocket connection guide and capability registration examples.

API quick reference:
- **API base URL**: https://api.dojo.tech
- **Environment selection**: Sandbox and production both use `https://api.dojo.tech`; the API key determines which environment receives the request
- **Authentication**: `Authorization: Basic <api_key>` (literal `Basic ` prefix; do not base64-encode `api_key:`)
- **Version header**: `version: 2026-02-27`

WebSocket endpoint: wss://eu.ws.dojo.tech/epos. Send `Authorization: Basic <api_key>` (literal `Basic ` prefix; the key is NOT base64-encoded), `software-house-id`, and optional `reseller-id` as handshake headers.
Before any capability is routed to your EPOS, register it via PUT https://api.dojo.tech/epos/integrations/ws (WebSocket) or /epos/integrations/rest (REST). The body is a `capabilities` array of `{name, version}` objects (for example `{"name": "SearchOrders", "version": "v1"}`). Re-PUT the full list whenever you add or remove a method.
Integration model:
- The POS system registers the capabilities it implements, then Dojo calls those URLs.
- Use the REST or AsyncAPI contract depending on which capability transport you expose.
- Payment lifecycle operations still use the Dojo API.

Machine-readable specs:
- [Dojo API v3](https://docs.dojo.tech/api/v3/bundled.json)
- [EPOS Data API (REST)](https://docs.dojo.tech/epos-data/bundled.json)
- [EPOS Data API (AsyncAPI)](https://docs.dojo.tech/epos-data-asyncapi/bundled.yaml)

For complete integration, also load:
- `llms-core-concepts.txt` — shared entities, events, and domain vocabulary used across EPOS-backed products
- `llms-inperson-pat.txt` — table-session flows built on top of EPOS capabilities
- `llms-bookings.txt` — reservations and RMS synchronization flows built on the same contracts
- `llms-order-and-pay.txt` — customer ordering and payment flows that depend on EPOS capabilities
- `llms-payment-intents.txt` — payment lifecycle, refunds, and captures

This file contains all documentation content in a single document following the llmstxt.org standard.

## Areas

The **Area** entity represents physical areas within a location. Examples of areas would be "dining area", "beer garden" and "upstairs".

## Capabilities

In the Dojo EPOS Data API, **capabilities** represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.

See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for how each capability is registered with Dojo.

**Registering a capability:** the heading for each capability below (for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`) is the exact `name` value to send in the body of `PUT /epos/integrations/rest` or `PUT /epos/integrations/ws`. The version is sent alongside as a separate field (`"version": "v1"`); appending `V1` to the heading gives you the wire-level method Dojo invokes after registration (for example `RecordOrderPaymentByIdV1`). See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the full body schema.

For backwards compatibility, registration also accepts the four legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they are equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation` respectively. New integrations should prefer the wire-aligned form shown in the headings below.

### ListAreas
> See OpenAPI spec for GET endpoint details: https://docs.dojo.tech/epos-data/api#tag/Areas/operation/v1-list-areas
> See OpenAPI spec for ListAreasV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-ListAreasV1_Request
This capability enables listing areas from the POS system.

---

## Dojo Events

Dojo Events are notifications about changes relating to entities which are owned by the Dojo API and
allow a POS system to be able to react in near real time. These events are sent by Dojo with *at-least-once* semantics to a POS system,
via the
**HandleEvent** capability ([REST](https://docs.dojo.tech/epos-data/api/#tag/Events/paths/~1v1~1events/post) or [WS `HandleEventV1`](https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-HandleEventV1_Request)).

An event payload contains a unique event `id`, the `accountId` specific to the location for whom the event is intended, when the event was `createdAt`, the event type in `event`, and `data` about the event.

The Dojo Events API will always differentiate between the states of an entity, such as being created or updated. When an entity is created by Dojo, a **created** event will be sent, and when that entity is updated, a **status_updated** event will be sent.

The difference between these events and [POS Events](https://docs.dojo.tech/core-concepts/pos-events) is that these events pertain to entities owned by **Dojo** and are sent from **Dojo** to the **POS system**. In contrast, [POS Events](https://docs.dojo.tech/core-concepts/pos-events) pertain to entities owned by the **POS system** and are sent from the **POS system** to **Dojo**

Dojo Events function similar semantically to [Webhooks](https://docs.dojo.tech/development-resources/webhooks) in payload and functionality;
If both the capability and webhook for an event are registered, that event will need to be handled idempotently as per the principle of *at-least-once*, as it will be sent by Dojo twice.

## Event Types

Below is information about the various event types that can be sent by Dojo to the POS system, including why Dojo sends it, the data it holds, and links to the relevant entity documentation.

| **Event Type**       | **Description**                                                                                                                                                                                                                                                                                                                                                 | **Data** |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `payment_intent.created`       | Whenever a **[Payment Intent](https://docs.dojo.tech/payments/manage-payments/payment-intent)** is created, this will trigger when a payment is prepared to be taken using a Dojo Product or if one is created through an [API Request](https://docs.dojo.tech/api/#tag/Payment-intents/operation/PaymentIntents_CreatePaymentIntent) |`paymentIntentId``paymentStatus``captureMode` |
| `payment_intent.status_updated`       | Whenever a **[Payment Intent](https://docs.dojo.tech/payments/manage-payments/payment-intent)** is updated, this will trigger when the status of a payment intent changes, such as being Captured or Cancelled.                                                                                          |`paymentIntentId``paymentStatus``captureMode`|

## Capabilities

In the Dojo EPOS Data API, **capabilities** represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.

See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for how each capability is registered with Dojo.

**Registering a capability:** the heading for each capability below (for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`) is the exact `name` value to send in the body of `PUT /epos/integrations/rest` or `PUT /epos/integrations/ws`. The version is sent alongside as a separate field (`"version": "v1"`); appending `V1` to the heading gives you the wire-level method Dojo invokes after registration (for example `RecordOrderPaymentByIdV1`). See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the full body schema.

For backwards compatibility, registration also accepts the four legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they are equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation` respectively. New integrations should prefer the wire-aligned form shown in the headings below.

### HandleEvent:payment_intent.created
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Events/paths/~1v1~1events/post
> See OpenAPI spec for HandleEventV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-HandleEventV1_Request
This capability enables the POS system to begin recording payments against **[orders](https://docs.dojo.tech/core-concepts/orders)** taken by Dojo products.

### HandleEvent:payment_intent.status_updated
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Events/paths/~1v1~1events/post
> See OpenAPI spec for HandleEventV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-HandleEventV1_Request
This capability enables the POS system to record status updates on payments against **[orders](https://docs.dojo.tech/core-concepts/orders)** taken by Dojo products.

---

## POS Events

POS Events are notifications about changes relating to entities which are owned by the POS system and
allow Dojo products to be able to react in near real time. These events are sent by the POS system to Dojo via the [submit event](https://docs.dojo.tech/api/#tag/Events/paths/~1epos~1events/post) endpoint in the Dojo API.

Each event payload only contains the `eventType` and the entity `id`, this minimal simple model has been chosen for the following reasons:

- Simplifies the implementation of sending events about entities whenever they are updated on the POS system.
- Reduces the risk of events with outdated data being processed by Dojo, instead Dojo will fetch the latest version of an entity via the relevant capability if required.

The POS Events API does not differentiate between created and updated events, as Dojo products do not require this distinction. When an entity is created on the POS system, an **updated** event is expected to be sent. In cases where an entity is deleted/cleared from the POS system an updated event should also be triggered. When a Dojo product attempts to fetch an entity and receives a **not found** error, the product will assume that the entity no longer exists on the POS system.

The difference between these events and [Dojo Events](https://docs.dojo.tech/core-concepts/dojo-events) is that these events pertain to entities owned by the **POS system** and are sent from the **POS system** to **Dojo**. In contrast, [Dojo Events](https://docs.dojo.tech/core-concepts/dojo-events) pertain to entities owned by **Dojo** and are sent from **Dojo** to the **POS system**.

## Event Types

Below is information about the various event types that can be sent by the POS system to Dojo, including when it is expected to be sent by the POS system, and links to the relevant entity documentation.

| **Event Type**       | **Description**                                                                                                                                                                                                                                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OrderUpdated`       | Whenever an **[order](https://docs.dojo.tech/core-concepts/orders)** on the POS system is created or changed, a change could be due to adding/removing `items` on the [order](https://docs.dojo.tech/core-concepts/parties), changing the price or quantity of an item, or auxiliary information such as the `note` on an order changing. Dojo expects to receive this event as different products may require up to date information. |
| `PartyUpdated`       | Whenever a **[party](https://docs.dojo.tech/core-concepts/parties)** on the POS system is created or changed, a change could be due to the `status` of the [party](https://docs.dojo.tech/core-concepts/parties) changing if they were to leave the venue or changed `hostNotes` after a waiter records information about the [party](https://docs.dojo.tech/core-concepts/parties).                                                                                                       |
| `ReservationUpdated` | Whenever a **reservation** on the POS system is created or changed, a change could be due to the `startTime`/`endTime` of a reservation being updated or the assigned `tableIds` being changed due to a different reservation requiring one of the tables.                                                                                     |

## API

### Submit Event
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/api/#tag/Events/paths/~1epos~1events/post
This allows a POS system to send events via the Dojo API, more information about getting started with the Dojo API can be found [here](https://docs.dojo.tech/payments/getting-started).

---

## Orders

The Order entity represents the core component of the Ordering API, containing all relevant information about an order placed by customers at a given location. An order can consist of multiple items, each with details like status, quantity, price, and applied modifiers. Dojo products create, modify and retrieve orders on the POS via the EPOS Data component of the Dojo API, these [capabilities](https://docs.dojo.tech/core-concepts/orders#capabilities) are documented below.

### Status

 The **Order Status** represents the various stages in an order’s lifecycle. As an order progresses from creation to fulfilment, its status will update to reflect its current state.

 | **Status** | **Description** |
 | --- | --- |
 | `New` | The order has been created but has not yet been processed. |
 | `Submitted` | The order has been submitted to the EPOS and is awaiting confirmation. |
 | `Confirmed` | The order has been confirmed by the EPOS and is awaiting kitchen or staff to accept. |
 | `Accepted` | The order has been accepted by the kitchen or staff for preparation. |
 | `Preparing` | The items in the order are currently being prepared. |
 | `Prepared` | The items have been fully prepared and are ready for service or collection. |
 | `Ready` | The order is ready for delivery or collection by the customer. |
 | `Finalized` | The order has been completed and paid for, and no further changes can be made. |
 | `Canceled` | The order has been canceled and is no longer active. |
 | `Failed` | The order has encountered an error and failed to process. This may require further investigation. |

 These statuses help track the state of each order and ensure that any integrated systems can react to updates in a consistent manner.

## Capabilities

In the Dojo EPOS Data API, **capabilities** represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.

See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for how each capability is registered with Dojo.

**Registering a capability:** the heading for each capability below (for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`) is the exact `name` value to send in the body of `PUT /epos/integrations/rest` or `PUT /epos/integrations/ws`. The version is sent alongside as a separate field (`"version": "v1"`); appending `V1` to the heading gives you the wire-level method Dojo invokes after registration (for example `RecordOrderPaymentByIdV1`). See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the full body schema.

For backwards compatibility, registration also accepts the four legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they are equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation` respectively. New integrations should prefer the wire-aligned form shown in the headings below.

### CreateOrder
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-post-orders
> See OpenAPI spec for CreateOrderV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-CreateOrderV1_Request
This capability allows the creation of new orders within the POS system. It is essential for handling customer orders and storing relevant order details.

### GetOrderById
> See OpenAPI spec for GET endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-get-orders-orderId
> See OpenAPI spec for GetOrderByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-GetOrderByIdV1_Request
This capability enables Dojo to retrieve detailed information about a specific order using its unique order ID. This is crucial for order tracking and status updates.

### CancelOrderById
> See OpenAPI spec for DELETE endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-delete-orders-orderId
> See OpenAPI spec for CancelOrderByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-CancelOrderByIdV1_Request
This capability provides the ability to cancel an order within the POS system, preventing further modifications or processing. Cancellations are performed using the order’s unique ID. The POS system can reject a `CancelOrder` reqeuest if the order is not in a state where it can be cancelled.

### SearchOrders
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/paths/~1v1~1orders~1search/post
> See OpenAPI spec for SearchOrdersV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-SearchOrdersV1_Request
This capability enables searching for orders based on various criteria. It supports filtering and pagination to help Dojo products efficiently find orders within the POS system. Each Dojo product has different requirements on what filters must be implemented which can be found on the product documentation page(s).

### RecordOrderPaymentById
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-post-record-order-payment
> See OpenAPI spec for RecordOrderPaymentByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-RecordOrderPaymentByIdV1_Request
This capability allows Dojo to record a payment against an order. All payments recorded this way will be sent with their `paymentIntentId` which is unique and can be used for both deduplication and to control the lifecycle of the payment with operations like Get and Reversal.

### CreateOrderLock
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-post-order-lock
> See OpenAPI spec for CreateOrderLockV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-CreateOrderLockV1_Request
This capability allows Dojo to acquire a lock on orders before making modifications to it like recording payments or adding items.
These locks allow the EPOS to know when an Order being modified and give Dojo the guarantee that the Order will not be modified externally while these operations are taking place.
Dojo will only try to acquire when making modifications, for other purposes fetching an eventually consistent snapshot of an Order from the EPOS through GetOrder should always be possible.

| Registered capabilities    | Behaviour |
| -------- | ------- |
| RecordOrderPaymentById | Dojo will send the RecordOrderPaymentById request, if a Conflict error is returned Dojo will attempt to reverse the payment    |
| RecordOrderPaymentById, CreateOrderLock, DeleteOrderLock | Dojo will first try to create the order lock with a long expiry. If successful it will try to record one or multiple payments then delete the lock.     |
| RecordOrderPaymentById, CreateOrderLock, DeleteOrderLock, ExtendOrderLock    | Dojo will first try to create the order lock with a short expiry. If successful it will try to record one or multiple payments. If the payment session takes longer, it will extend the lock. After the payment session has finished we will delete the lock.    |

### DeleteOrderLock
> See OpenAPI spec for DELETE endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-delete-order-lock
> See OpenAPI spec for DeleteOrderLockV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-DeleteOrderLockV1_Request
This capability allows Dojo to release a lock on orders.
If both this and CreateOrderLockRequest are registered then Dojo will only attempt to RecordOrderPaymentById against an order after having successfully acquired a lock and will release the lock once the payment is recorded.

### ExtendOrderLock
> See OpenAPI spec for PUT endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-put-extend-order-lock
> See OpenAPI spec for ExtendOrderLockV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-ExtendOrderLockV1_Request
This capability allows Dojo to extend an existing lock.
It is not required for the locking flow to function, registering this will allow Dojo to create locks with a shorter initial expiry and extend as needed.

### GetOrderBillById
> See OpenAPI spec for GET endpoint details: https://docs.dojo.tech/epos-data/api#tag/Orders/operation/v1-get-order-bill
> See OpenAPI spec for GetOrderBillByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-GetOrderBillByIdV1_Request
This capability allows the terminal to request a Bill - a printable version of the Order. The EPOS can customise the fields and layout of the Bill on a per request basis.

---

## Parties

The **Parties** entity represents a group seated in the venue, and should uniquely identify them in the POS for the entire duration of their stay. **Dojo Bookings** infers availability by the presence of a party at a table. Each party can include additional details such as deposits, special requests and allergen information.

## Capabilities

In the Dojo EPOS Data API, **capabilities** represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.

See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for how each capability is registered with Dojo.

**Registering a capability:** the heading for each capability below (for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`) is the exact `name` value to send in the body of `PUT /epos/integrations/rest` or `PUT /epos/integrations/ws`. The version is sent alongside as a separate field (`"version": "v1"`); appending `V1` to the heading gives you the wire-level method Dojo invokes after registration (for example `RecordOrderPaymentByIdV1`). See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the full body schema.

For backwards compatibility, registration also accepts the four legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they are equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation` respectively. New integrations should prefer the wire-aligned form shown in the headings below.

### CreateParty
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Parties
> See OpenAPI spec for CreatePartyV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-CreatePartyV1_Request
This capability allows the creation of a new **Party** within the POS system. It is essential for assigning parties to a table and storing relevant order details.

### GetPartyById
> See OpenAPI spec for GET endpoint details: https://docs.dojo.tech/epos-data/api#tag/Parties/operation/v1-get-parties-partyId
> See OpenAPI spec for GetPartyByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-GetPartyByIdV1_Request
This capability allows Dojo to retrieve up-to-date information about a specific **party** seated at a table, such as the unique ID, table ID and status.

### UpdateParty
> See OpenAPI spec for PUT endpoint details: https://docs.dojo.tech/epos-data/api#tag/Parties/operation/v1-put-parties-partyId
> See OpenAPI spec for UpdatePartyV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-UpdatePartyV1_Request
This capability allows Dojo to update the POS with additional **party** information given after initial booking. For example, this could be the party's allergen requirements in the form of guestRequests, a change in booking time or a new expected end-time.

### DeletePartyById
> See OpenAPI spec for DELETE endpoint details: https://docs.dojo.tech/epos-data/api#tag/Parties/operation/v1-delete-parties-partyId
> See OpenAPI spec for DeletePartyByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-DeletePartyByIdV1_Request
This capability allows Dojos Epos Data API to delete a specific **party** by using the party Id.

### SearchParties
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Parties/operation/v1-search-parties
> See OpenAPI spec for SearchPartiesV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-SearchPartiesV1_Request
This capability allows Dojo to retrieve parties from a POS. By default, the POS should not return parties where `endTime` is set, including them only where `completedOnly` is "true".

---

## Reservations

The **Reservation** entity represents an upcoming party or booking. Reservations may be created, updated and deleted by Dojo products. Once a reservation has been seated within the venue, it becomes a [party](https://docs.dojo.tech/core-concepts/parties).

## Capabilities

In the Dojo EPOS Data API, **capabilities** represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.

See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for how each capability is registered with Dojo.

**Registering a capability:** the heading for each capability below (for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`) is the exact `name` value to send in the body of `PUT /epos/integrations/rest` or `PUT /epos/integrations/ws`. The version is sent alongside as a separate field (`"version": "v1"`); appending `V1` to the heading gives you the wire-level method Dojo invokes after registration (for example `RecordOrderPaymentByIdV1`). See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the full body schema.

For backwards compatibility, registration also accepts the four legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they are equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation` respectively. New integrations should prefer the wire-aligned form shown in the headings below.

### CreateReservation
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Reservations
> See OpenAPI spec for CreateReservationV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-CreateReservationV1_Request
This capability allows for the creation of a new **reservation** within the POS system. This enables the creation of bookings on the POS by Dojo products.

### GetReservationById
> See OpenAPI spec for GET endpoint details: https://docs.dojo.tech/epos-data/api#tag/Reservations/operation/v1-get-reservations-reservationId
> See OpenAPI spec for GetReservationByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-GetReservationByIdV1_Request
This capability allows Dojo to retrieve up-to-date information from the POS about a specific **reservation** such as the start-time, end-time and any booked table IDs.

### UpdateReservation
> See OpenAPI spec for PUT endpoint details: https://docs.dojo.tech/epos-data/api#tag/Reservations/operation/v1-put-reservations-reservationId
> See OpenAPI spec for UpdateReservationV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-UpdateReservationV1_Request
This capability allows Dojo to update **reservations** on the POS. For example, this could be changes to the reservation's covers, time-slot or table IDs.

### DeleteReservationById
> See OpenAPI spec for DELETE endpoint details: https://docs.dojo.tech/epos-data/api#tag/Reservations/operation/v1-delete-reservations-reservationId
> See OpenAPI spec for DeleteReservationByIdV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-DeleteReservationByIdV1_Request
This capability allows Dojos to delete a specific **reservation** by using the reservation Id.

### SearchReservations
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Reservations/operation/v1-search-reservations
> See OpenAPI spec for SearchReservationsV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-SearchReservationsV1_Request
This capability allows Dojo to retrieve **reservations** from a POS and can include filters such as table Id and time slot.

---

## Tables

The Table entity represents a physical place within a location and/or area where customers are designated. Tables are mostly static, but expected to change if there are physical layout changes at a location. Tables may have multiple active [orders](https://docs.dojo.tech/core-concepts/orders) and/or [parties](https://docs.dojo.tech/core-concepts/parties) sitting at them at any one time.

## Capabilities

In the Dojo EPOS Data API, **capabilities** represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.

See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for how each capability is registered with Dojo.

**Registering a capability:** the heading for each capability below (for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`) is the exact `name` value to send in the body of `PUT /epos/integrations/rest` or `PUT /epos/integrations/ws`. The version is sent alongside as a separate field (`"version": "v1"`); appending `V1` to the heading gives you the wire-level method Dojo invokes after registration (for example `RecordOrderPaymentByIdV1`). See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the full body schema.

For backwards compatibility, registration also accepts the four legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they are equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation` respectively. New integrations should prefer the wire-aligned form shown in the headings below.

### SearchTables
> See OpenAPI spec for POST endpoint details: https://docs.dojo.tech/epos-data/api#tag/Tables/operation/v1-search-tables
> See OpenAPI spec for SearchTablesV1 endpoint details: https://docs.dojo.tech/epos-data/ws/api#spec-operation-receive-SearchTablesV1_Request
This capability enables searching for Tables from the POS system.

---

## Terminal Sessions

[Terminal sessions](https://docs.dojo.tech/payments/accept-payments/in-person-payments/pay-at-counter/terminals/create-session) allow you to establish a connection with the terminal (via the Dojo API) and prepare it for processing payments. The terminal session will update its [notification events](https://docs.dojo.tech/api#tag/Terminal-sessions/operation/TerminalSession_Create) throughout its lifecycle which can be displayed to the POS user.
> **Tip:** Both **Sale** and **Matched Refund** require a [payment intent](https://docs.dojo.tech/api#tag/Payment-intents) to be created and passed in the request body, where an **Unlinked Refund** is not linked to a previous captured sale and can be initiated without.
>
>
> ### Status
>
> The **Terminal Session Status** represents the various stages in a terminal session lifecycle. As a **Terminal Session** progresses from creation to fulfilment, its status will update to reflect its current state.
>
> | **Status** | **Description** |
> | --- | --- |
> | `InitiateRequested` | The request to begin the session has been submitted to the Terminal and is awaiting confirmation. |
> | `Initiated` | The session has been confirmed by the Terminal and is awaiting payment to be taken. |
> | `Authorized` | The payment has been authorized pending [final capture](https://docs.dojo.tech/payments/manage-payments/capture) (Pre-authorization). |
> | `Captured` | Payment has now been captured and no further updates will be made to the session. |
> | `CancelRequested` | The request to cancel the session has been submitted to the Terminal and is awaiting confirmation. |
> | `Canceled` | The session has been canceled by the Terminal. |
> | `SignatureVerificationRequired` | Payment has been captured pending [signature verification](https://docs.dojo.tech/api#tag/Terminal-sessions/operation/TerminalSession_Signature). |
> | `SignatureVerificationAccepted` | Payment has been captured after successful signature verification [signature verification](https://docs.dojo.tech/api#tag/Terminal-sessions/operation/TerminalSession_Signature). |
> | `SignatureVerificationRejected` | Payment has been reversed following rejection of [signature verification](https://docs.dojo.tech/api#tag/Terminal-sessions/operation/TerminalSession_Signature).|
> | `Expired` | The terminal session has expired. |
> | `Declined` | Payment has been declined by the card issuer. |
>
> These statuses help track the state of each session and ensure that any integrated systems can react to updates in a consistent manner.
>
> ---
>
> ## EPOS Data API Integration Explorer
>
> Use the explorer below to see which capabilities are needed to support an integration with each Dojo product. Some of the core concepts are used across multiple integrations to provide the maximum uptake for the least amount of development.
>
>
>
> ---
>
> ## EPOS Data
>
> > This section contains the REST version and Websockets version of the EPOS Data API.
>
> The EPOS Data API offers two integration methods for connecting the EPOS system with Dojo: **REST** and **Websockets**. These methods
> can be used separately or in combination depending on your system architecture and data accessibility needs.
>
> ## [REST](https://docs.dojo.tech/epos-data/api)
>
> The **REST API** is ideal for centralized architectures where the EPOS data is hosted on a centralized server. Dojo
> can interact with the server using standard HTTP methods to access or modify data.
>
> Recommended for:
> - Centralized EPOS data hosted on a server.
> - Stateless communication, where each API request is independent.
> - Asynchronous data access and batch processing.
>
> ## [Websockets](https://docs.dojo.tech/epos-data/ws/api)
>
> Visit the [getting started](https://docs.dojo.tech/explore/epos-data/getting-started) page for instructions on establishing a WebSockets connection.
>
> The **Websockets API** is best for environments where EPOS data resides locally and must be shared with Dojo in real-time. It maintains
> a persistent connection between the EPOS and Dojo to enable low-latency, continuous data transmission without repeated polling.
>
> Recommended for:
> - On-premise EPOS data that requires real-time synchronization.
> - Persistent, low-latency communication like live transaction updates.
>
> ## Dojo API Key
>
> An [API Key](https://docs.dojo.tech/development-resources/api-keys) is required to access the EPOS Data API:
>
> - You need a key that starts with `sk_sandbox_` to access to the sandbox environment.
> - You need a key that starts with `sk_prod_` to access the production environment.
>
> In the following examples, `{{API_KEY}}` is used as a placeholder for the actual API Key.
>
> ## Registering capabilities
>
> Register your EPOS Data API endpoints as capabilities in the [Dojo API](https://docs.dojo.tech/api) so Dojo knows which functions are available. **Registration is mandatory**: until you register a capability, Dojo will not invoke it on your EPOS, even if your WebSocket connection is open and your REST endpoint is reachable.
>
> * PUT [/epos/integrations/rest](https://docs.dojo.tech/api#tag/Capabilities/paths/~1epos~1integrations~1rest/put) (REST)
> * PUT [/epos/integrations/ws](https://docs.dojo.tech/api#tag/Capabilities/paths/~1epos~1integrations~1ws/put) (WebSockets)
>
> The valid `capabilities[].name` values are the ones documented in [Core concepts](https://docs.dojo.tech/core-concepts/orders) — for example `SearchOrders`, `GetOrderById`, `CreateOrderLock`, `RecordOrderPaymentById`, `GetOrderBillById`, `ListAreas`. **The heading text on each capability page is the exact `name` to send in the registration body**; the version is sent alongside as `"version": "v1"`. Appending `V1` to the registration name gives the wire-level method that Dojo will invoke on your EPOS (for example `SearchOrdersV1`, `RecordOrderPaymentByIdV1`).
>
> Event-driven capabilities are registered per event type using a colon qualifier; each registered event type maps to the same `HandleEventV1` wire method:
>
> - `HandleEvent:payment_intent.created`
> - `HandleEvent:payment_intent.status_updated`
>
> The full set of registerable capability names accepted today is:
>
> | Domain | Capability names |
> | --- | --- |
> | Orders | `CreateOrder`, `GetOrderById`, `CancelOrderById`, `SearchOrders`, `RecordOrderPaymentById`, `GetOrderBillById`, `AddOrderItems` |
> | Order locking | `CreateOrderLock`, `DeleteOrderLock`, `ExtendOrderLock` |
> | Order and Pay (preview) | `CalculateOrder`, `SubmitCalculatedOrder`, `SearchMenus` |
> | Parties | `CreateParty`, `GetPartyById`, `UpdateParty`, `DeletePartyById`, `SearchParties` |
> | Reservations | `CreateReservation`, `GetReservationById`, `UpdateReservation`, `DeleteReservationById`, `SearchReservations` |
> | Tables & areas | `SearchTables`, `ListAreas` |
> | Events | `HandleEvent:payment_intent.created`, `HandleEvent:payment_intent.status_updated` |
>
> **Note:** For backwards compatibility, the registration endpoint also accepts the legacy names `GetOrderBill`, `RecordOrderPayment`, `UpdatePartyById`, and `UpdateReservationById` — they're equivalent to `GetOrderBillById`, `RecordOrderPaymentById`, `UpdateParty`, and `UpdateReservation`. New integrations should use the wire-aligned form (the one shown in the table above).> **Note:** `AddOrderItems`, `CalculateOrder`, `SubmitCalculatedOrder`, and `SearchMenus` are accepted by `PUT /epos/integrations/{rest,ws}` today, but their request and response contracts are still being finalised. Don't register them in production until the corresponding REST/WS pages are published. If you're integrating with Order and Pay and need any of these, contact your Partnership Development Manager (PDM).
You can view the currently registered capabilities using the following API call:

```curl
curl --location 'https://api.dojo.tech/epos/integrations' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}'
```

This will return a list of registered capabilities. If no capabilities are registered, the response will be empty:

```json
{
    "restIntegrations": [],
    "wsIntegrations": []
}
```

Once you've registered capabilities, the response includes one entry per integration with the capability list, the version Dojo will invoke, and an `updatedAt` timestamp:

```json
{
    "restIntegrations": [],
    "wsIntegrations": [
        {
            "createdAt": "2026-04-27T10:08:46.421Z",
            "capabilities": [
                {"name": "SearchOrders",                              "version": "v1", "updatedAt": "2026-04-27T10:08:46.421Z"},
                {"name": "GetOrderById",                              "version": "v1", "updatedAt": "2026-04-27T10:08:46.421Z"},
                {"name": "RecordOrderPaymentById",                    "version": "v1", "updatedAt": "2026-04-27T10:08:46.421Z"},
                {"name": "HandleEvent:payment_intent.created",        "version": "v1", "updatedAt": "2026-04-27T10:08:46.421Z"},
                {"name": "HandleEvent:payment_intent.status_updated", "version": "v1", "updatedAt": "2026-04-27T10:08:46.421Z"}
            ]
        }
    ]
}
```

### Example: registering `GetOrderById` on REST

To register a capability (e.g., `GetOrderById`), you can use the following command:

```curl
curl --location --request PUT 'https://api.dojo.tech/epos/integrations/rest' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}' \
--data '{
  "capabilities": [
    {
      "name": "GetOrderById",
      "version": "v1"
    }
  ],
  "auth": {
    "authType": "basic",
    "basic": {
      "username": "dojo",
      "password": "password"
    }
  },
  "url": "https://f815-86-22-100-52.ngrok-free.app/some/path/v1/orders/{orderID}"
}'
```

This command registers the `GetOrderById` capability on the REST adapter, making it accessible through the provided URL with basic authentication.

### Example: registering capabilities for WebSockets

The WebSocket variant uses the same `capabilities` array but **does not** include `auth` or `url` — Dojo invokes the methods over the WebSocket connection your EPOS opens to `wss://eu.ws.dojo.tech/epos`.

```curl
curl --location --request PUT 'https://api.dojo.tech/epos/integrations/ws' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}' \
--data '{
  "capabilities": [
    {"name": "ListAreas",                                  "version": "v1"},
    {"name": "SearchTables",                               "version": "v1"},
    {"name": "SearchOrders",                               "version": "v1"},
    {"name": "GetOrderById",                               "version": "v1"},
    {"name": "GetOrderBillById",                           "version": "v1"},
    {"name": "CreateOrderLock",                            "version": "v1"},
    {"name": "ExtendOrderLock",                            "version": "v1"},
    {"name": "DeleteOrderLock",                            "version": "v1"},
    {"name": "RecordOrderPaymentById",                     "version": "v1"},
    {"name": "HandleEvent:payment_intent.created",         "version": "v1"},
    {"name": "HandleEvent:payment_intent.status_updated",  "version": "v1"}
  ]
}'
```

Send the full list of capabilities you implement on every PUT — capabilities omitted from the body will not be routed to your EPOS until you re-register them.

## Using the EPOS tester tool
> **Tip:** The EPOS tester tool is used to verify your [partner-hosted](https://docs.dojo.tech/api-explorer#hosted-by-partners) integration. Don't have access to the EPOS tester tool? Reach out to your Partnership Development Manager.
The API reference for the EPOS tester tool can be found [here](https://docs.dojo.tech/epos-tester-tool/api/).

Once you have registered your capabilities, you can test the integration using the **epos-tester-tool**. This service allows you to test
individual API methods or entire transaction flows. It’s designed to facilitate development by letting you trigger Dojo calls programmatically
and verify their correctness in real-time.

For example, to list all available flows and their parameters, use the following request:

```curl
curl --location 'https://api.dojo.tech/epos-tester-tool/flows' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}'
```

One such flow is `Get Order`, which you can trigger using this command:

```curl
curl --location 'https://api.dojo.tech/epos-tester-tool/flows' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}' \
--data '{
  "flow": "Get Order",
  "params": {
    "orderId": "testOrderID"
  }
}'
```

The response is the bare flow ID as a quoted JSON string, for example:

```json
"d00aa12a-7fb8-46a2-a22d-f4b560298353"
```

To check the status, run:

```curl
curl --location 'https://api.dojo.tech/epos-tester-tool/flows/d00aa12a-7fb8-46a2-a22d-f4b560298353' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}'
```

The response will detail the status of the flow and list every step it went through. If a capability like `GetOrder` was not registered, the response will indicate failure and suggest registering the method:

```json
{
    "finishedAt": "2024-09-19T15:03:23.529Z",
    "flowID": "d00aa12a-7fb8-46a2-a22d-f4b560298353",
    "flowName": "Get Order through EPOS Data API",
    "startedAt": "2024-09-19T15:03:21.226Z",
    "status": "FAILURE",
    "steps": [
        {
            "additionalInformation": [
                "GetOrder method not found",
                "Please register the GetOrder method on an EPOS Data API adapter"
            ],
            "finishedAt": "2024-09-19T15:03:23.524Z",
            "name": "Check whether GetOrder has been registered",
            "startedAt": "2024-09-19T15:03:21.51Z",
            "status": "FAILURE"
        }
    ]
}
```

---

## Opening a WebSockets connection

>Obtain your API key and publish your first message.

## Step 1. Get your API keys

Use the [Dojo developer portal](https://docs.dojo.tech/development-resources/portal) to receive your API key (`apiKey`). Reach out to your Partnership Development Manager (PDM) if you do not have access to the developer portal. This is required to receive and send messages to the API.

## Step 2. Open a WebSocket connection to the EPOS Data API

To start integrating with the EPOS Data API, you can use our test endpoint. This endpoint allows you to simulate payments on the card machine,
making it easier for you to develop and test your integration:

```
wss://eu.ws.dojo.tech/epos
```

Ensure you're using a WebSocket client that enables you to set the required headers:

| Header Name | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Authorization | Basic authorization is used to authenticate your requests to the API using your API key as the value, for example: Basic `$apiKey`. |
| `reseller-id` (optional)| Identifies the reseller who sells software on behalf of the EPOS company. This value will be unique and provided by Dojo to each reseller.                                                                                                                                                                                                                                                                                                                   |
| `software-house-id` | Identifies the EPOS company whose software is generating the request. This value shouldn't be configurable as it will remain the same for all customers using particular EPOS software. This value will be provided by Dojo.                                                                                                                                                                                                                                 |

All of these values will be provided by Dojo. If you're unsure about any of them, reach out to your PDM.
> **Tip:** Despite the scheme name, do **not** base64-encode your API key. The literal value
> `Basic <api_key>` (with the `sk_sandbox_` or `sk_prod_` key inserted as-is) is what
> the gateway expects.
## Step 3. Confirm the WebSocket connection

Ensure that you were able to successfully establish the WebSocket connection. Look out for any errors and reach out to your PDM if you require further assistance.

## Step 4. Register the capabilities you implement

The connection alone is not enough — Dojo will only route a JSON-RPC method to your EPOS once you've **registered** that capability. Do this once, then update it whenever you add or remove a method. See [Registering capabilities](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities) for the request body and a worked example, and the per-capability pages under [Core concepts](https://docs.dojo.tech/core-concepts/orders) for the exact `name` value to register for each method.

## Connection lifecycle

Once the WebSocket is open, Dojo multiplexes every JSON-RPC method invocation over the single connection. Keep these in mind when implementing the EPOS side:

- **Long-lived connection.** The connection is expected to stay open. Dispatch each incoming JSON-RPC request to a handler concurrently and reply with a matching `id` on the same socket; the gateway correlates requests and responses by JSON-RPC `id`.
- **Keepalive.** Send a WebSocket ping at least every 30 seconds when otherwise idle, and respond to incoming pings within a few seconds. Connections that go silent for several minutes may be closed by the gateway.
- **Reconnect on close.** If the connection drops, reconnect with exponential backoff (e.g. 1s, 2s, 4s, capped at ~30s) and resume serving requests. In-flight requests are not replayed across reconnects — Dojo will retry on its side as needed, so handle requests **idempotently** based on the JSON-RPC `id` if you persist any side-effects before responding.
- **One connection per `software-house-id` deployment.** Open one connection per logical EPOS instance. Multiple concurrent connections from the same `software-house-id` are not load-balanced; only one will receive routed requests at a time.
- **HTTP/1.1 only.** WebSocket upgrade is not supported over HTTP/2. If your client library defaults to HTTP/2, force HTTP/1.1 for the handshake.

## Next steps

You're now ready to start building your EPOS integration!