# Dojo Order and Pay Documentation > Guides for integrating Order and Pay — self-service order creation, pay-only flows, and POS capability coordination. 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 ` (literal `Basic ` prefix; do not base64-encode `api_key:`) - **Version header**: `version: 2026-02-27` Order and Pay combines customer checkout with POS order-management capabilities. It relies on payment intents for payment collection and on shared order entities exposed by the POS. 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 Order and Pay integration, also load: - `llms-core-concepts.txt` — shared order, event, and payment-recording vocabulary - `llms-payment-intents.txt` — checkout, authorization, capture, refund, and webhook behavior - `llms-epos.txt` — EPOS capability registration and contract details This file contains all documentation content in a single document following the llmstxt.org standard. ## Order and Pay > This section covers integrating with Dojo Order and Pay. Order and Pay is an integrated, self-service solution that enables the creation and management of [orders](https://docs.dojo.tech/core-concepts/orders) on the POS without the need for physical hardware, as well as the paying of those orders from a customer device or other Dojo product, empowering customers with a seamless, integrated experience. Customers can interact with a visual menu on their device to place orders and complete payment, or pay later from the same interface. These updates are shared with the POS in real-time, allowing busy venues to serve customers faster. ## Order Entity The [Order](https://docs.dojo.tech/core-concepts/orders) 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 such as status, quantity, price, and applied modifiers. ## Order 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 POS and is awaiting confirmation. | | `Confirmed` | The order has been confirmed by the POS and is awaiting preparation. | | `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. --- ## Flows > **Info:** The capabilities mentioned on this page must be registered with the **EPOS Capabilities API** prior to initiating an Order and Pay flow, > learn more [here](https://docs.dojo.tech/api-hosting/epos-data#registering-capabilities). The following diagram demonstrates how the **Order and Pay** product will interact with Dojo and the POS system for creating orders and completing payments: ![](https://docs.dojo.tech/images/order-and-pay/order-and-pay-flow.jpg) **Flow diagram: Order And Pay Flow** ```mermaid sequenceDiagram actor C as Customer participant B as DOJO Backend participant P as POS C->>B: Create order B->>B: Create payment intent B-->>C: Redirect to checkout C->>B: Completes checkout flow B->>B: Dojo captures payment B->>P: CreateOrder P->>P: Record payment, update order status P-->>B: 200 OK B-->>C: Order confirmation ``` # Step-by-step: Order and Pay ## Step 1: Customer creates order to Dojo The first stage of the Order and Pay flow is triggered when a customer, having accessed a list of venue products using the Dojo Order and Pay interface, creates an order by adding one or more items to the basket and advancing to the payment screen. ## Step 2: Dojo creates a Payment Intent and captures the payment **Main Page**: [Payment Intents](https://docs.dojo.tech/payments/manage-payments/payment-intent) Once the order has been initiated via the Order and Pay interface, Dojo will pre-authorise the payment by creating a Payment Intent and initiating a checkout flow for the customer. This payment is to be captured once the POS has confirmed the order. This also generates a Payment Intent which can be used to recall payment details such as the authorization code, card type and receipt data upon payment completion. ## Step 3: Dojo creates an order on the POS > 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 **Main page**: [Orders](https://docs.dojo.tech/core-concepts/orders) The next step in is for Dojo to create the customer order within the POS, using the `CreateOrder` capability. The request will contain fields such as item data, type of order and payment details, including the `paymentIntentId`. It may also contain any additional modifiers or discounts, for example, if specified. The POS should respond to Dojo with a 200 response to confirm that this has been received and that the payment has been acknowledged and recorded, and the response should inlcude additional data such as the relevant status. > **Info:** In any calls made from the POS to Dojo through the [Dojo API](https://docs.dojo.tech/api), such as to [retrieve the Payment Intent status](https://docs.dojo.tech/payments/manage-payments/payment-intent#check-payment-intent-status), Dojo will refer to the POS "order ID" by `externalId`, this can be useful when retrieving payment details such as receipt data upon payment completion, for example. ## Step 4: Dojo displays order status to customer After receiving a successful response from the POS to the RecordOrderPaymentById request, Dojo will inform the customer of the outcome and given order status through the **Order and Pay** customer interface. The following diagram demonstrates how the **Order and Pay** product will interact with Dojo and the POS system to exclusively complete payments: ![](https://docs.dojo.tech/images/order-and-pay/pay-only-flow.jpg) **Flow diagram: Pay Only Flow** ```mermaid sequenceDiagram actor C as Customer participant B as DOJO Backend participant P as POS C->>B: Request open orders B->>P: SearchOrders P-->>B: List of open orders B-->>C: Show open orders C->>B: Choose order to pay B->>P: GetOrderById P-->>B: GetOrderById response B->>B: Create payment intent B-->>C: Redirect to checkout C->>B: Completes checkout flow B->>B: Dojo captures payment B->>P: Record Payment request P->>P: Record payment, update order status P-->>B: Record Payment response B-->>C: Show updated order ``` # Step-by-step: Pay-only ## Step 1: Customer retrieves orders > 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 **Main page**: [Orders](https://docs.dojo.tech/core-concepts/orders#search-orders) The first stage of the pay-only flow is triggered when a customer attempts to retrieve open orders using the Order and Pay interface. Dojo will request these from the POS using the [SearchOrders](https://docs.dojo.tech/capabilities/orders) capability, refining the request by certain filters such as table ID. Once Dojo has received the orders requested, these will be displayed to the customer for selection. ## Step 2: User selects order, Dojo requests order details > 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 **Main page**: [Orders](https://docs.dojo.tech/core-concepts/orders#get-order-by-id) The user will then select the relevant order from their table's order list: this will trigger a call from Dojo to retrieve the details of that specific order from the POS before attempting to record the payment, ensuring that the amount and other details are up to date. ## Step 3: Dojo creates a Payment Intent and authorises the payment > 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 **Main page**: [RecordOrderPaymentById](https://docs.dojo.tech/core-concepts/orders#record-order-payment) Once the correct order has been selected by the customer, Dojo will create a Payment Intent and initiate the checkout flow for the customer to capture payment. Dojo will now capture the pre-authorised payment. Once captured, Dojo will use a RecordOrderPaymentById request containing the relevant `orderId` to inform the POS that the payment is captured. A `paymentIntentId` will be included in this request which should be recorded and can be used for retrieving payment details such as receipt data upon payment completion. The POS should respond to this request with a 200 response to indicate that the payment has been acknowledged and recorded. The POS should also respond with the current order "status" to show any changes that may have occurred to this attribute. If the payment cannot be recorded, such as in the event of a mismatching value being submitted in the RecordOrderPaymentById request, the POS should reject the request with a `409` error and the relevant `errorType`, for example: "Conflict". This will trigger a payment reversal on the customer app and prompt the user to reattempt the payment. **Note**: The POS may receive multiple RecordOrderPaymentById requests from different iniating customers, such as in the instance of a table of guests paying for their own individual items, and therefore should be prepared to see multiple requests. ## Step 4: Dojo displays updated order status to customer After receiving a successful response from the POS to the RecordOrderPaymentById request, Dojo will inform the customer of the outcome and given order status through the **Order and Pay** customer interface.