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 (WS HandleEventV1). Events are only delivered over WebSockets; if you're integrating over REST, subscribe to the equivalent webhooks instead.
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 is that these events pertain to entities owned by Dojo and are sent from Dojo to the POS system. In contrast, 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 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 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 | paymentIntentIdpaymentStatuscaptureMode |
payment_intent.status_updated | Whenever a Payment Intent is updated, this will trigger when the status of a payment intent changes, such as being Captured or Cancelled. | paymentIntentIdpaymentStatuscaptureMode |
terminal_session.created | Whenever a new Terminal Session is initiated. | terminalSessionIdstatepaymentDetails |
terminal_session.status_updated | Whenever a Terminal Session moves to a new state in the transaction lifecycle, such as authorized, captured, or declined. | terminalSessionIdstatepaymentDetails |
terminal_session.signature_verification_required | Whenever a Terminal Session requires the cardholder to verify their signature before it can continue. | terminalSessionIdstatepaymentDetails |
terminal_session.notification | Whenever a Terminal Session displays a notification to the cardholder, for example prompting them to insert their card. The notification is reported in state. | terminalSessionIdstatepaymentDetails |
For an example terminal_session.* event payload, see the terminal session payload on the Webhooks page — Dojo Events share the same payload structure.
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 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 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
This capability enables the POS system to begin recording payments against orders taken by Dojo products.
HandleEvent:payment_intent.status_updated
This capability enables the POS system to record status updates on payments against orders taken by Dojo products.
HandleEvent:terminal_session.created
This capability enables the EPOS to react when a new terminal session has been initiated successfully.
HandleEvent:terminal_session.status_updated
This capability enables the EPOS to react when a terminal session moves to a new state in the transaction lifecycle, such as authorized, captured, or declined. The new state is reported in data.state.
HandleEvent:terminal_session.signature_verification_required
This capability enables the EPOS to react when a terminal session requires the cardholder to verify their signature before the session can continue.
HandleEvent:terminal_session.notification
This capability enables the EPOS to react when a terminal session displays a notification to the cardholder, for example prompting them to present, insert, or remove their card. The specific notification is reported in data.state.