This section provides an overview the core concepts in the Transaction Engine API.

Before the API is used the client must obtain a valid JSON Web Token. The JWT is required in all secured API calls. See Authorization for more details.

All API operations are performed on a unique client session. The session must be created before it can be used to create and populate transactions. Once a client is done it should preferrably logout to close the session. Abandoned sessions are eventually removed.

• The client creates a session with provided settings. Settings include country, store, workstation identifiers and optional layout configuration.
• The Transaction Engine returns a unique session ID to be used to access resources within the session context.
• The client can proceed to perform operations on the session, for example:
  • Add entities to the receipt. An entity is typically added by scanning a barcode on the client and then submit it using the register entity API call.
  • The entity is processed and validated on the Transaction Engine.
  • The updated active receipt is returned with details about the added entity and rendering data to visualize the receipt on the client.
• When all items are added, the client can initiate payment for the transaction.
• The Transaction Engine will process and validate the payment. Finalization of an order typically involves external integrations and can also include printing to a phyiscal printer among other things.
• When the receipt is finalized a final copy of the receipt is returned to the client.
• The client can continue to create new transactions or perform other operations in the same session
• Once done, the client should end the session to remove it permanently.

Client response

All operations that manipulate the receipt returns a client response wrapper object that contains one of the following:

• A boolean flag to indicate that nothing changed
• An updated receipt model. Depending on the session settings, this is either the full receipt or the changes delta
• A prompt request in which the Transaction Engine requests additional user input from the client

Clients must use their session in a strict request-response flow, except for the async push events. This means that a client must wait for a response (or the timeout) before sending the next request. If this contract is broken the API will not behave correctly and will break with unexpected behavior.

If the second request would be sent before the first response the Transaction Engine would either

1. interrupt the first request and serve the second request,
2. return an HTTP 500 error or
3. reject the second request with an HTTP 4XX

What scenario the client will see depends on timing and the type of requested resources.

There is a few exceptions to the request-response restriction, where the APIs allow concurrent requests.

• Image resources
• Status event subscriptions are active while issuing other requests

The Transaction Engine can request additional input on most operations using a prompt request construct.

• A client adds an entity that will require additional input. It could for example be an age restricted item, or an item that requires an alarm tag to be removed.
• The Transaction Engine processes the item and determines that additional input is required
• A prompt request is created and returned to the client. The Transaction Engine will suspend processing.
• The client should display the request for additional input to its user and allow them to act on it. In the case of age restriction, the prompt request would ask for the customer's age. In the case of an alarm tag, it would remind the user to remove the tag.
• When the input request is handled, the client sends the prompt response to the Transaction Engine.
• The Transaction Engine will continue processing. The result of the processing could result in more prompt requests.
• When the processing is completed, the Transaction Engine will return the active receipt with the added entity.

Controllable prompt requests

A controllable prompt request is a request for input that can be cancelled, modified or fulfilled from the Transaction Engine. Examples when controlled prompts are common include

• EFT payments
• Manager override use cases
• Prompt requests that can be managed by a remote attendant

When a prompt request is controllable, clients must subscribe to events in order to detect when the request is updated or closed.

• A client adds an entity that will dispatch a request to an external system.
• While waiting for a response, the Transaction Engine returns a controllable prompt that can offer feedback or allow for ways to cancel the operation.
• The Transaction Engine can send one or more change prompt events to request that the client updates its user interface representation of the original prompt request. If the prompt allows for user input, the client can choose to submit a prompt response which will be processed by the Transaction Engine.
• When the external system completes processing the Transaction Engine can request for a prompt to be using a close prompt event.
• When the client hides the prompt, it should send a prompt response back to the Transaction Engine to get end the interaction with an updated receipt as response.

The receipt consists of entities that represents the lines in a receipt. The two major pieces of information in an entity are

• The type safe information about the underlying receipt data. This is for example saleItem or loyaltyInfo data structures.
• A layout block to help clients render a visual representation of the receipt.

The type safe information can be used in whatever way clients see fit. The data is documented and available as API models.

The layout and especially the DSL layout rows may however never be parsed in an attempt to deduce data about the entity. The structure of rows and cells vary depending on state not disclosed to the client. The layout information should only be used for its intended purpose, which is to render an entity similar to that on a printed receipt.

See also receipt rendering for more details on how to process layout DSL.

Status events is an asynchronous push notification feature that complements the Open API. It allows clients to listen for asynchronous changes to their session between, but especially during, an active request-response flow.

Events should be used by clients to handle use cases such as

• A controllable prompt request from the Transaction Engine
• An interactive EFT payment
• Status notifications from any of the supported events that may be created in-between operations. This could for example be the suspended order count that is updated whenever a transaction is suspended within the store.

This section explains how API resources are used in user experience and user interface.

The menu tree resources in the API are intended to be used together with the command execution operations. Clients can get the menus and render them as a tree menu structure.

• When a menu option with children is selected, display the children
• When an option without children is selected, use the command to run the operation
• The menu will only include choices that the user is authorized to use
• Choices have optional conditions that should be used on the client to
  • Disable choices depending on the session state
  • Provide the current selected entity as an input parameter if required

If menus are used, clients are recommended to load them after creating a new session. The menus support caching so it is efficient to check for changes.

The API supports both a default menu and named menus. What names that are available depends on configuration in the Transaction Engine. Typically, Tranaction Engine offers the following named menus, but it is not limited to these.

• default - the default menu (always available)
• payment - payment specific menu
• item - options to manipulate a receipt entity (availability may depend on application type)

For most interactive clients, the default DSL layout is recommended. It provides clients with a data structure consisting of rows and columns, similar to a flex-box layout.

• Rows define basic font styling
• Cells contain a text value to be rendered in the specified relative width and aligned and truncated according to the defined properties

The layout provided by the Transaction Engine is often configured to be similar to the printed receipt. If the receipt is rendered with the provided layout data it ensures that the content and visualization is the same across all sales channels. The limitation with the provided layout is that it can't make sure of device-specific features to enhance the user experience.

The price lookup (PLU) tree is similar to the menu trees but provides an hierarhical tree structure to browse and optionally register items that may not have a barcode. This may include fruit, bread and heavy items.

• An PLU entry with children is a category. When selected it should display its children.
• When a PLU entry with a posIdentity is selected, the value should be provided as input to the register entity resource.
  • The PLU entry includes unit of measure to allow clients to provide weight as an input parameter when registering the item. If not provided, the Transaction Engine will request the weight with a prompt request

Clients should load the PLU after the session has been created. It is recommended to update the price lookup tree between each receipt to receive updates to the tree structure. The resource supports caching and will only return a new structure when changed.

The purpose of the input information query is to support flexible user experience when details about the input may be required before trying to register it at the Transaction Engine. Examples of use cases for input information:

• Self checkouts that should validate the item weight before sending it to the Transaction Engine.
• Clients that need access to the item name or other properties for the user experience.
• Validation of the input to check what type of value it represents in Transaction Engine. Typically, this means to check if the input is an item barcode, a loyalty card or something uknown.

The downside with the input information query is that it introduces an extra API call, so it's use should be weighted against its effect on throughput in the client.

The Transaction Engine has a concept of input modes. The input mode indicates how the Transaction Engine will process input. For example, if Transaction Engine is in REFUND_ONLY mode, all registered entities will be interpreted as a request to register a refund.

The input mode is typically changed by the user through selecting a menu choice in the menu tree. Depending on the client UX it could be useful to include a hint in the UI to indicate what input that is currently active. To make this easy, each ClientResponse includes the current input mode.

Resources to create and manage the client session.

Resources to create and manage transactions