Operation Definitions

The POS Event Stream API contains a set of requests and corresponding responses designed to send event messages to a client application, in real time, as POS API operations occur. Each POS Event Stream request and event notification has a defined set of elements.

Message content is formatted as JSON elements. Each message includes JSON elements to identify the source of the message, a version identifier, a unique message identifier, and the type of message.

The POS Event Stream Operation Definitions documentation includes the following sections:

Data Models - Information on the POS Event Stream request and responses.
Event Messages - A list of events with descriptions.
create_order Example - An example of a msg_data payload.
Response Codes - A list of POS Event Stream response codes with descriptions.

Data Models

Data Model - General Structure

Each POS Event Stream message includes one or more of these common elements.

Field Name	Type	Required	Description
`source`	string	Yes	Identifies the source of the message. The value is not validated. The source value is helpful for diagnostic purposes.
`version`	string	No	Identifies the POS Event Stream JSON data contract
`msg_id`	string	Yes	A unique string value to identify this specific request. The `msg_id` value is echoed back in the response to the message. This allows the sender to match the response with the request.
`msg_type`	string	Yes	Identifies the function to be performed with the message content. This value is returned in the response to the message.
`msg_resp`	string	No	When a request is received, the recipient must decrypt the `msg_data` content, if it is encrypted, then send a response message with `msg_resp` value “ack” to acknowledge receipt of the request
`msg_data`	string	No	Contains any data required for the message. The `msg_data` value must be encrypted using the Advanced Encryption Standard (AES) 256 Data Encrypting Key (DEK), then encoded as a base64 value. Note Only the `init_client` request includes an unencrypted value for element `msg_data`.

init_client

POS API sends the init_client request to the client application. This is the first request that POS API sends to the client application when the socket connection is established.

The message content includes the RSA public key that the client application uses to encrypt its response. POS API sends the init_client request to the client application when the Transmission Control Protocol (TCP) socket connection is first established. The init_client request includes the RSA public key that the client application uses as the Key Encrypting Key (KEK) to encrypt the Advanced Encryption Standard (AES) 256 Data Encrypting Key (DEK) that the client application sends to POS API in the register_client request.

Field Name	Type	Description
`msg_type`	string	The `init_client` request type
`msg_data`	msg_data Object	The `msg_data` content is not encrypted for the `init_client` request element message. The key is Base64 encoded and the escaped JSON fragment is sent as a string.

init_client msg_data Object

Field Name	Type	Description
`key`	string	The key is the RSA public key that the client application uses to encrypt the `msg_data` in the `register_client` request

init_client Sample Code

Sample Request Body

{
  "source": "xenial",
  "version": "1.0",
  "msg_id": "18B34EBF-5E59-4271-9879-D2B100D025E7",
  "msg_type": "init_client",
  "msg_data": "{\"key\":\"binary key encoded as base64 string"}"
}

Sample Response Body

{
  "source": "client name",
  "version": "1.0",
  "msg_id": "18B34EBF-5E59-4271-9879-D2B100D025E7",
  "msg_type": "init_client",
  "msg_resp": "ack"
}

register_client

The client application sends the register_client request to POS API after it acknowledges the init_client request. The client application generates an Advanced Encryption Standard (AES) 256 Data Encryption Key (DEK) and stores it in Base64 format to the aes_data_key element.

The JSON string with the aes_data_key, key_id, and secret_key will then need to be encrypted with the RSA public key that it received from POS API in the init_client request and stored in the msg_data in Base64 format. The integrator’s key_id and secret_key values are unique to each of our partners and must be stored securely so they are not exposed to any other actor.

Field Name	Type	Description
`msg_type`	string	The register_client request information
`msg_data`	msg_data Object	Before the `register_client` request is sent to POS API, the client application must encrypt the contents of `msg_data` using the RSA public key it received in the `init_client` request from POS API. The provided RSA public key is 2048 bit and is in DER-encoded or ASN.1 BER format.

register_client msg_data Object

Field Name	Type	Required	Description
`aes_data_key`	string	Yes	The `aes_data_key` is the AES 256 data encryption key that the client application creates, and is used by both the client application and POS API to encrypt all subsequent messages. It should be in Base64 format.
`key_id`	string	Yes	The integrator’s `key_id` provided by us to the integrator or partner who authored the client application
`secret_key`	string	Yes	The `secret_key` provided by us to the integrator or partner who authored the client application

register_client Sample Code

The client will first create a JSON string with the required information. This JSON string then needs to be encrypted using the RSA public key received in the init_client message and Base64 encoded. This will be the value for the msg_data element.

{ "aes_data_key": "+6ptgsRKCLNdp3anfVEK9K0tQasUSyJ9ndR5S2Ae+gI=", "key_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "secret_key": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb" }

This is what the register_client message will look like when sent to POS API.

{
  "source": "client name",
  "version": "1.0",
  "msg_id": "ac0701e8-cd5e-4d41-9f33-1e0317568aab",
  "msg_type": "register_client"
  "msg_resp": "",
  "msg_data": "IpFx7WggrNs5R+ehurMNRywd2/JMimzrL71fUEAQc2JGYdPuIV7EzTh1k4ycVw
0bdx+RFprtaW33bCHmFJn3cVwdqXSIgBi/gZdjvkKSBT7Jpf04voZcs7Gsevk8pXilvKaDXWZBdyb
VUAcVq93j4a2NxvMYGkJO/lfsJHXhCHXDM53FwK8/MtaLVLv62xjTU0xwiDETxyVYL4KFRJfgmR4p
SiPT8ED1VLzGiEJ7jsf9F4XGTbTVPNagDA1QkD+45UDcZa1NA1JqoAPbzc2MCLuLEXhkmAAAaHT0v
VVwt5nhdTS85DhVbM7Sa+ZLuiY8T1f5PTLBJ6ZPhKg7vxkOLQ=="
}

Sample Response Body

POS API acknowledges receipt of the register_client request after it decrypts the value of element msg_data.

{
  "source": "xenial",
  "version": "1.0",
  "msg_id": "ac0701e8-cd5e-4d41-9f33-1e0317568aab",
  "msg_type": "register_client",
  "msg_resp": "ack"
}

POS API creates a new RSA encryption public/private key pair for each connection. This is an example of a public/private key pair. The RSA key is 2048 bit and is in DER-encoded or ASN.1 BER format which is also the same as Privacy-Enhanced Mail (PEM) without the header and footer.

Note

The RSA public key is provided to the client and is used with the register_client only.

RSA Public Key Example

MIIBIDANBgkqhkiG9w0BAQEFAAOCAQ0AMIIBCAKCAQEAi5vBG3CdxdTpoqz+n3
QnZDDT662qdT9U6M6zXiT0I1mT0iZtZSWZgrItXAwnoTwy/j37B9A+6J2ZRlhe
J5ZAd2mPk6KvMVdcW7Jel5jc0XsCNolC6pxzElF+/odCRkIMIFDBvyD45pz13i
o+Jw8vjZFkYAyI3Exx3/mmGjzJfmlTi+Yksv4O44pDjMiAWvQ6e/XoRL1ipoEv
GJuVjOkgsmqHpRSBwT20jNAL/OiUfXlDnmTr5R+s8qhAaUvxXWudmXGxUHbrj5W
923L+WdUzcRWJVkNdyZ3l8sOZHPv2m38++afhWLPqDr+UkN5GNnB0gmW3Aco7hD
FeuWSZ6iXuqQIBEQ==

RSA Private Key Example

Note

The RSA private key is for example only and is not provided to the client.

MIIEuwIBADANBgkqhkiG9w0BAQEFAASCBKUwggShAgEAAoIBAQCLm8EbcJ3F1Om
irP6fdCdkMNPrrap1P1TozrNeJPQjWZPSJm1lJZmCsi1cDCehPDL+PfsH0D7onZ
lGWF4nlkB3aY+Toq8xV1xbsl6XmNzRewI2iULqnHMSUX7+h0JGQgwgUMG/IPjmn
PXeKj4nDy+NkWRgDIjcTHHf+aYaPMl+aVOL5iSy/g7jikOMyIBa9Dp79ehEvWKmg
S8Ym5WM6SCyaoelFIHBPbSM0Av86JR9eUOeZOvlH6zyqEBpS/Fda52ZcbFQduuPl
b3bcv5Z1TNxFYlWQ13JneXyw5kc+/abfz75p+FYs+oOv5SQ3kY2cHSCZbcByjuEM
V65ZJnqJe6pAgERAoIBAASxVhZvWTPThscU369PMs2WFAfsBbrMWOeOejJ+A+dfg
+SkyZfWPRfBJhibTKBPeAiLw5kAi8uVbpBZBVDtYvlB71BBtCQUJYZPI3LPW1JV4
fTs8zDCkdnknyjTEUlaa/h7L2Ltvzk7Drfe//AaU1ioYgeH82PowSN+tfyUVDfhE
hBKL1xQX2dWbqccPgmTfdnDgGe9fJZUv38ml9rTnG+ZjNTxNmQTXQRc3g1slSppz
1WeTCrgP6Row43aGEhahZrkCtsBYLGw1/p8W8NSujjGB8QBpzWS/oZGBFNKzAwyH
lWOOyEHkqB76kjdb6ssBn6XXb5I9e/wkQCn9Ib1gLECgYEAwEc59kdz0RjNb8vbG
pyiZkrqzLHRz3XeBG4JqXjhYRuoUnkcqtA7cVRydQh2+5AJXg2ZTs4AfBYNc75ON
cGxUjyGGajKFgoH01aP7GZagMIdykRgsk3qkn6/UJoCYv6hmErer75bSo4Ng25n8
19cNuzTV3wTJ3003fqUqcB0bO0CgYEAueANLXEzJ4hxd9VlMCFt9CKS74SmWLhJ6
aPVxmXwUZ6qF2zvxM/CM/aSyOUTQz+kDV2mQxuPy4FuEu7laTM1RJzrVLRD2N9A0
SjvaACdjpX0WAqxfQHeP1lhR9UIXTIKoD2B0oO3VVpLlyq6mLK2fF97Oqi8f2THp
utLRXqpzS0CgYAtPe+FPf0iI/QaThVvrGJya/sC/KnWdhYfKPM270QW2VTIHH83Q
A38jFcqmJR3bS9hbJyLA0tofajP8IrfeN5ts+NRVORBa8WbI20okI3D8XBr09qET
pGL4ZZtUWn5LNq6a/gpWfdc1iFMGfpXYbtYN7lBwtdUle5SWRPrtNAZoQKBgQCDN
L4B9Y2FUUEJS1Z8U9UkzRxs1hsRcwb/RnjIR/TuUeF58oshg5gkrg1Cg5UgaSiB5
8Cn1zhTamvRIRpoYGHWFGnhcC/kYVrt/sccPKtztSTy2l8rEGClMAhu8LqcI1LLd
rX+Ap+HiwgueIO3FL0Mf6JHhiq0RyOE4lNAGlm+AQKBgEhg/zpLyAPe8t6gM268+
wCpwGP3zgaYWXHCnzaK8lwNAgndCaIZNKhwoc9gjJabPSyZb4NWh7sF+/aoH8Bnx
aefkK5YgfG0KTnboPZ+lrI6Foh4dQziXxwakotq3yWs0mdgQ6zADr3FgYSliTxfN
bVpwnKAVAnW99CnUYeCL2Zq

client_registered

POS API sends the client_registered request to the client application after it acknowledges the register_client request and then validates the client application’s values from the register_client request.

The value for the msg_data element is encrypted for the client_registered request and all future messages. POS API encrypts the data using the Advanced Encryption Standard (AES) 256 Data Encrypting Key (DEK) received from the client application in the register_client request and Base64 encoded. For decryption details, see msg_data.

Field Name	Type	Description
`msg_type`	string	The client_registered request information
`msg_data`	msg_data Object	`msg_data` is encrypted using the AES 256 key provided in the register_client and Base64 encoded. The AES encryption uses CBC mode, PKCS7 padding, and the IV is zeros.

client_registered msg_data Object

Field Name	Type	Required	Description
`result`	string	Yes	The values of “success” or “fail” indicate whether POS API successfully validated the data provided by the client application in the `register_client` request
`result_code`	string	Yes	A code to indicate the reason for a failure to register the client application
`description`	string	Yes	A text description of the reason for a failure to register the client application

client_registered Sample Code

Sample Request Body

{
  "sourcSae": "xenial",
  "version": "5.0",
  "msg_id": "65FB085D-8049-4CEF-ADC6-CE126E0FC6BB",
  "msg_type": "client_registered",
  "msg_data": "iK5Wl/4ytaUaObt44F5r3BksR8Unu+Cds9D3IOE6e+/E7tBjApX
tYp4tM1BX1lzSnMmJ0bcQhIu/v+fVfhvraQ=="
}

Sample Success msg_data After Encryption Body

{
  "result": "success",
  "result_code": "0",
  "description": "success"
}

Sample Failure msg_data After Encryption Body

{
  "result": "fail",
  "result_code": "10",
  "description": "Integrator credentials failed validation"
}

Sample Response Body

{
  "source": "client name",
  "version": "1.0",
  "msg_id": "65FB085D-8049-4CEF-ADC6-CE126E0FC6BB",
  "msg_type": "client_registered",
  "msg_resp": "ack"
}

event_info

After client_registered is validated successfully, POS API begins sending event information to the client as events occur. Some, but not all, events could have full order information. The msg_data is encrypted using the Advanced Encryption Standard (AES) 256 Data Encrypting Key (DEK) received from the client application in the register_client request and is Base64 encoded.

For more information on events, see Event Messages.

Field Name	Type	Description
`msg_type`	string	The event_info request information
`msg_data`	msg_data Object	For the decryption details, see client_registered. For the event details, see msg_data Object.

Field Name

Type

Description

msg_type

string

The event_info request information

msg_data

msg_data Object

For the decryption details, see client_registered.

For the event details, see msg_data Object.

event_info msg_data Object

Field Name	Type	Required	Description
`event`	string	Yes	The event name, such as create_order
`event_time`	string	Yes	The Coordinated Universal Time (UTC) time that event occurred. For example, `"event_time": "2023-09-19T14:18:57.546Z"`
`terminal`	string	Yes	Describes the terminal where the event occurred
`terminal.name`	string	Yes	Specifies the name of the terminal where the triggering event occurred. For example, `"name": "DT Terminal 3"`.
`terminal.number`	string	Yes	Specifies the number of the terminal where the triggering event occurred. The value is a short identifier that can be alphanumeric, but is typically numeric. For example, `"number": "3"`.
`application`	application Object	No	Describes the application in which the event occurred
`employee`	employee Object	No	This object describes the employee who triggered an event
`order`	string	No	The order content when applicable to the event. For more information about the Order Object, see Online Ordering API - Order Object.

application Object

Field Name	Type	Description
`name`	string	The name of the application where the event occurred. For example, `“name”: “POS”`.
`version`	string	The version of the application where the event occurred. For example, `“version”: “3.8.10-1234”`.

Field Name

Type

Description

name

string

The name of the application where the event occurred.

For example, “name”: “POS”.

version

string

The version of the application where the event occurred.

For example, “version”: “3.8.10-1234”.

employee Object

Field Name	Type	Description
`id`	string	The internal unique identifier (UID) of the employee. For example, `“id”: “64259c113d7d41ebf35c0714”`.
`code`	string	The merchant-assigned unique identifier of the employee. For example, `“code”: “653488”`.
`name`	string	The name of the employee. For example, `“name”: “Mary Smith”`.

event_info Sample Code

Sample Request Body

{
  "source": "xenial",
  "version": "5.0",
  "msg_id": "5B80E323-6755-4F13-AE93-3CB8F3EBD178",
  "msg_type": "event_info",
  "msg_data": "RhhQHF9RuPXxEMa86a9wXnXNKYpgbczRAsnEyNodgodxwMzAPfICE0gr
JSuggKAH8sdcjsGMQuS1Dgkuyo/0YNvxhQm11VpOQqJstXeeLFc5aQPnaXe3gL6MmHQNLwh
eaLTRV9LRiX+bMtmwOguHsmpOEGy9No6gl2wt0rMf9EfU8oCJOMFEhEO2vfNJDkQATpvtD0
j7KWxzuSyh+bMVdZKK4RE0OhV/vuRWqt5OfQBg3Wnp9aQauYMXO0GgNZy7R4UHPcUb5ZaTn
wvROSmsj8j4uf5aywp0WR7nLyxzHqiBZE6u2oI667t
- - - CUT - - -
u2f8C4QIieGe9/kJAqPI4KiN6cTS0AQ5BsiTdH1X6LyY3RpEZxtXz5WNFSLcJW9PgBPUtj
cR5pOCWdso9G4HybXw4LZyn5hRjswRE3O64+sNHAAZd+oOjgyf69GlEE7wWbufqEoK2+1R
3MGtf4AYz3wocavAU3rHFWv96zcnVGqc8edkxNM9RHhxvo4ZddKlak5ZeE1EnNQwJal5dC
axZvsCvLMZ/emfRIhMsUOwin3j87uucCTFKt/xNJEAyrhWF7+Ti5i9isEhwKd5m4n8m8g
Q="
}

Sample Response Body

{
  "source": "client name",
  "version": "1.0",
  "msg_id": "5B80E323-6755-4F13-AE93-3CB8F3EBD178",
  "msg_type": "event_info",
  "msg_resp": "ack"
}

Note

The client application should acknowledge, or “ack”, the event_info request. For more information, see Socket Message Format.

If POS API fails to receive “ack” for some requests or for a period of time, it will close the connection and attempt to re-initialize the connection.

Event Messages

The following table lists the order-level event messages:

Event	Description
order_create	Published on creation of any order within POS API
order_receive	Published when an external order is received by POS API. For example, an order from Online Ordering.
order_suspend	Published when an order is “suspended” at POS API, which means the order session is ended and the order is persisted in an incomplete, not-yet-fulfillable state. This includes "suspend" and "park" for IRIS.
order_resume	Published when an existing order is loaded as the active order for order entry
order_save	Published when the active order is saved for later access and unloaded as the active order
order_total	Published when order is totaled from Order Entry or otherwise taken to the Payment screen from any entry point. For example, open order views and split check.
order_cancel	Published when an existing order is deleted before that deletion would be considered a void
order_void	Published when an existing order is deleted after that deletion would be considered a void
order_paid	Published when an order’s `payment_status` advances to “paid” which is when the order is fully paid
order_close	Published when an order is finalized
order_retender	Published when an order is re-tendered
order_check_in	Published when an order is checked in
order_ready	Published when all contents of an order are deemed ready to be served
order_fulfill	Published when all items on an order have been served/delivered to the customer
order_update	Published on every order update. This event is to be used in integrations like Order Confirmation and Kitchen Feeds that want immediate updates as orders change to determine what is updated. Our system may throttle this event with a timer, which means requiring at least 700ms between publishing. This is done in case multiple order updates occur within that time, only a single `order_updated` event is sent. Also, an operation such as converting an item from one to another which may delete one item and add another could be optimized to send the `order_updated` event after the entire operation is completed.

For additional information on events, see event_info.

create_order Example

Important

The order content in this example is a sample only and does not necessarily represent what will be received. The content is defined by the stream definition.

{
   "event":"order_create",
   "event_time":"2023-10-11T05:20:34.126Z",
   "terminal":{
      "number":"1",
      "name":"Terminal 1"
   },
   "application":{
      "name":"POS",
      "version":"3.8.73-4"
   },
   "employee":{
      "id":"5f1b545cdde54f0001a09b6b",
      "code":"653488",
      "name":"Mary Smith"
   },
   "order":{
      "_id":"c55fa0f0-9d5f-474e-b36b-5502368df667",
      "destination":{
         "entity_id":"58ff21b2f7f03e0001024872",
         "id":"carry-out",
         "consumption_type":"OffPremises",
         "external_id":"carry-out",
         "name":"Carry Out",
         "short_name":"OUT"
      },
      "origin":"025",
      "order_source":"In-Store",
      "expo_number":"184",
      "business_date":"2023-10-10T00:00:00.000Z",
      "company_id":"5f19d79f6295f000087badd5",
      "order_number":"100284",
      "order_type":"order",
      "order_status":{
         "status":"pending"
      },
      "payment_status":"open",
      "segments":[
         {
            "title":"bag",
            "num":1,
            "id":"4b4d969c-5092-4c9b-8ce9-601f61d13694"
         }
      ],
      "site_info":{
         "company":{
            "id":"5f19d79f6295f000087badd5",
            "name":"Matheson's"
         },
         "id":"5f3dded3e789950007c747cf",
         "name":"Blowing Rock",
         "store_number":"025",
         "timezone":"US/Eastern",
      },
      "state":"pending",
      "time":{
         "created":"2023-10-11T05:20:34.126Z",
         "last_modified":"2023-10-11T05:20:34.166Z"
      },
      "version":"137",
      "guest_count":1,
      "order_source_ext":{
         "name":"In-Store",
         "order_source_id":"InStore"
      },
      "items":[
         
      ],
      "fulfillment_status":"pending",
      "customer":{
         "last_name":"Williams"
      },
      "day_part_info":{
         "day_part_type_id":"58f86f95a42b1bfc7a6e7d94",
         "day_part_type_name":"Late Night",
         "external_id":null
      }
   }
}

Response Codes

The following response codes are used by POS Event Stream API:

Code	Response Message	Description
0	Success	The request or operation completed successfully
1	Fail	Generic failure
2	Fail	Invalid value for Integrator `key_id`
3	Fail	Invalid value for integrator `secret_key`
4	Fail	No active subscription found for the integrator
5	Fail	No active subscription found for the site
6	Fail	Client cannot be validated offline
7	Fail	Invalid value for AES Data Encrypting Key (DEK)
8	Fail	Integrator provided does not match subscription
9
10	Fail	Integrator credentials failed validation
11
12
13
14
15
16
17
18
19
20
98		Encryption error
99		Decryption error with key encryption key (RSA Decryption)
100		Missing `msg_data` element (not encrypted or decryption error)
101		Bad message format

Operation Definitions

Data Models

Data Model - General Structure

Note

init_client

init_client msg_data Object

init_client Sample Code

register_client

register_client msg_data Object

register_client Sample Code

Note

Note

client_registered

client_registered msg_data Object

client_registered Sample Code

event_info

event_info msg_data Object

application Object

employee Object

event_info Sample Code

Note

Event Messages

create_order Example

Important

Response Codes

Search results