Data structures

A list of data structures, which are used for data exchange between POS and Qerko. We provide JSON schemas (opens in a new tab) for comfortable validation.

Bill

POS sends this structure when Qerko needs info about a bill. It carries the metadata as well as the contents of the bill.

Property	Type	Required	Description
additionalData	any	No	POS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. You will receive it in Payment.additionalData.
created	string	No	Timestamp of the bill creation in ISO 8601 (opens in a new tab) extended format. Example: `2019-04-13T00:22:57+01:00`
currency	string	Yes	Used currency in ISO 4217 format. All prices in this structure must use the same currency. Example: `CZK`
denyDiscounts	boolean	No	Whether Qerko can apply another discount. Set it to TRUE when there already is an internally applied discount by POS and other discounts are unwanted. This is related to discounts provided by restaurant owners only. Discounts paid by Qerko or third parties (sponsors like breweries) aren't affected by this property. FALSE ‒ Qerko can apply a discount. TRUE ‒ Qerko can’t apply a discount.
allowTip	boolean	No	Can the customer add a tip? Default: `true`
allowPartialPayment	boolean	No	Can the customer pay only a subset of the items? Default: `true`
discountOffer	BillDiscountOffer	No	Discount offered to the guest by the restaurant owner. Qerko has many sources of discounts, so Qerko's list will be extended by this offer.
id	string	Yes	Unique identifier of the bill from POS. This identifier is used in payment structure when Qerko returns the whole or part of the bill to be paid.
items	BillItem[]	Yes	Unpaid items on the bill.
name	string	No	Name of the bill to be shown to the customer. If not provided, Qerko will try to generate some.

BillDiscountOffer

POS sends this structure as a part of the Bill structure. It carries info about a discount offer. It is used as a discount offer from POS, specifically from the restaurant. The customer will probably accept it, unless he has a better offer from another source (loyalty program, Qerko, etc.).

Property	Type	Required	Description
additionalData	any	No	POS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. If the customer decides to accept the offer, you will receive it in Payment.discount.additionalData.
name	string	Yes	Human readable name. It will be visible on the receipt and in a Qerko app.
percent	string	Yes	Discount value percentage. It is not possible to offer other types of discounts, because of difficulties with paying only a part of the bill. Example: `5` means 5% discount, `7.5` means 7.5% discount

BillItem

POS sends this structure as a part of Bill structure and receives it as a part of Payment structure. It carries info about an item on a bill or item related to a payment.

Property	Type	Required	Description
additionalData	any	No	POS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. You will receive it in Payment
id	string	no	POS identifier of bill item. This value is just returned by Qerko when the same bill item is used (fully or partially). In other words POS sends it in bill structure and Qerko returns it in payment structure.
minQuantity	string	no	Minimum payable quantity. It also defines the quantity precision. Qerko will allow only multiples of minQuantity as split quantity. If minQuantity = 0, then the item cannot be split. If quantity is divisible by minQuantity then Qerko will make it possible to split the item, else the item will be passed through Qerko with unchanged quantity. Example: If minQuantity = 1 and quantity is integer, then the item can be split into lower integer quantities. If minQuantity = 1 and quantity is decimal, then the item cannot be split. Example: `0.001`, `1`,... Default: `1`
name	string	Yes	Human readable name of bill item. It will be visible on the receipt and in a Qerko app. Example: `The Two-Hand Burger`
price	string	Yes	Total price for bill items including taxes. Price can be zero, or negative. Example: `110.00`
quantity	string	Yes	Sold amount. It can be decimal and negative. Example: `5` (5✕ beer), `0.7` (child portion)
tags	string[]	No	Something identifying groups of products or categories of products, etc. categorization. Can be used for loyalty programs, discounts or something else. Used values depend on the relation between POS and Qerko configuration. Used in discount definition, ex: "10% off for coffee if a tag:dessert is ordered as well" Example: `["burger", "beef", "meat"]`
subItems	BillSubItem[]	No	The list of subitems that are added to this item. They can’t be paid separately.

BillSubItem

This structure represents a part of an item that is added to the parent item. Price to pay is the sum of the BillItem price and all its subItems.

Property	Type	Required	Description
id	string	Yes	POS identifier of bill sub item. This value is just returned by Qerko when the same bill subitem is used. In other words POS sends it in bill subitem structure and Qerko returns it in payment structure.
name	string	Yes	Human readable name of bill subitem.
price	string	Yes	Price which will be added to BillItem in application.

Discount

This structure is used as part of the Payment structure. It carries info about a discount that was applied to the payment. Splitting the discount among bill items is completely up to POS. POS must include the discount into Receipt.taxInfo.

Property	Type	Required	Description
additionalData	any	No	If source=pos this property will contain whatever data POS has sent in the BillDiscountOffer structure.
name	string	Yes	Human readable text for the receipt
source	string	Yes	The source of the discount: POS ‒ Discount from POS, sent in Bill ‒ Discount from Qerko, Qerko will pay the costs PROMO ‒ Discount was set up in web administration (opens in a new tab) LOYALTY ‒ Discount was set up in web administration (opens in a new tab) as a part of a loyalty program.
value	string	Yes	The absolute value of the discount. Currency is from the payment. Example: `100` when the discount was one hundred

Error

This structure is used in various situations to report an error.

Property	Type	Required	Description
message	string	Yes	Human readable text describing the error. It is never presented to the customer.
code	string null	No	When the error occurs in Qerko server it contains one of Error codes or null. When the error occurs in POS, it can have a special effect, which is defined by the respective method.

FiscalInfo

POS sends this structure as a part of the Receipt structure. It carries info about a fiscal report related to the receipt. This object is treated as template data. Feel free to add any relevant info that the restaurant might want to print on the receipt. It will be possible to have a per-restaurant template in the future. If you implement for a country which is not documented here, send us your requirements, we will make them the standard for the country in this document.

Czechia

Property	Type	Required	Description
footerLines	string[]	No	Additional lines to print on the receipt below eet* parameters.
footerText	string	No	Additional text to print on the receipt below footerLines.
headerLines	string[]	No	Additional lines to print on the receipt above headerText.
headerText	string	No	Additional lines to print on the receipt above eet* parameters.

Slovakia

Property	Type	Required	Description
footerLines	string[]	No	Additional lines to print on the receipt below the uid parameter.
footerText	string	No	Additional text to print on the receipt below footerLines.
headerLines	string[]	No	Additional lines to print on the receipt above headerText.
headerText	string	No	Additional lines to print on the receipt above the uid parameter.
uid	string	No	Slovakian unique identifier of the receipt (unikátny identifikátor pokladničného dokladu)
bkp	string	No	Slovakian BKP which will appear on the receipt when the uid is not sent.

Austria

Property	Type	Required	Description
footerLines	string[]	No	Additional lines to print on the receipt below the uid parameter.
footerText	string	No	Additional text to print on the receipt below footerLines.
headerLines	string[]	No	Additional lines to print on the receipt above headerText.
headerText	string	No	Additional lines to print on the receipt above the uid parameter.
qrData	string	Yes	An utf-8 string data, which is used to create a QR code for the lower part of the receipt.

Germany

Property	Type	Required	Description
footerLines	string[]	No	Additional lines to print on the receipt below the uid parameter.
footerText	string	No	Additional text to print on the receipt below footerLines.
headerLines	string[]	No	Additional lines to print on the receipt above headerText.
headerText	string	No	Additional lines to print on the receipt above the uid parameter.
qrData	string	Yes	An utf-8 string data, which is used to create a QR code for the lower part of the receipt.

MethodCallRequest

POS receives this structure, although it is called request, in a response from the long-polling endpoint. It requests the POS to call a method.

Property	Type	Required	Description
uuid	string	No	Identifier of the method call. If not provided, then the sender does not expect the receiver to send a response.
method	string	Yes	The name of the method to call. See Methods.
args	any[]	Yes	Array of method arguments.

MethodCallResponse

POS sends this structure, in a request to the long-polling endpoint, although it is called response. It carries the result of a method call. It is sent as a reaction to receiving a MethodCallRequest.

Property	Type	Required	Description
uuid	string	Yes	Identifier of the method call which was in the MethodCallRequest.
error	Error	No	Error which has occured, ifany.
result	any	No	Result of the corresponding method call.
calledMethod	string null	No	Method which produced this response. Qerko sends this every time. POS can ignore it. Provided for easier statelessness.

Payment

POS receives this structure for paymentStart(...) method or as a response to getPayment(...) or from the payment endpoint. Total price is: sum(items[i].price) + tipBrutto - discount.value

Property	Type	Required	Description
additionalData	any	No	Additional data from the Bill structure.
currency	string	Yes	Currency code in ISO 4217 (opens in a new tab)format.
discount	Discount	No	Discount applied to the payment.
id	string	Yes	Identifier of the payment. Qerko generates it for every
idBill	string	Yes	Identifier of the related bill.
idCustomer	string	Yes	Unique identifier of the customer who pays. For the loyalty program on the POS side. POS can identify the user when there was a previous call to method pairCustomer. Else the POS can track users activity, but the user remains anonymous.
items	BillItem[]	Yes	List of items, which are paid by the payment.
state	string	Yes	STARTED ‒ The payment process has just started PROCESSING ‒ The payment is processed. PAID ‒ The payment is paid. It is the final state. CANCELLED ‒ The payment is cancelled. It is the final state. ERROR ‒ The payment ended with an error. Manual action must be taken to solve this error and manually switch the transaction to CANCELED.
parts	PaymentPart[]	Yes	This is an array which holds info for splitting the payment among payment providers.
tipBrutto	string	Yes	Tip for the restaurant personnel.
tipNetto	string	Yes	Qerko might take a tip commission, so there will be a tip after the commission subtraction. This will be based on the agreement with the restaurant. POS should show this value to the restaurant personnel.

PaymentPart

POS receives this structure as a part of the Payment structure. It holds information about a part of payment which has been paid using a payment provider.

Property	Type	Required	Description
provider	PaymentProvider	Yes	This is the payment provider that was used to fulfill this payment part.
total	string	Yes	This is how much was paid using this payment provider.

PaymentProvider

POS receives this structure as a part of PaymentPart structure. It holds information about used payment provider. Each provider can be enabled/disabled per restaurant on the Qerko web page. There might be different rules for different types according to local laws.

Property	Type	Required	Description
id	string	Yes	A unique identifier of this payment provider.
name	string	Yes	A human readable provider name Example: `Qerko`, `A meal ticket, Ltd.`, `Some smart card, Ltd.`, etc.
type	string	Yes	This is for description of the type of the transaction, so POS can apply correct rules according to local laws. `CARD` This means online payment using card BANK_TRANSFER - This means payment by bank transfer INVOICE - This means exchange of funds based on an invoice VOUCHER - This includes vouchers, coupons and other pre-paid types. MEAL_TICKET - This means payment by meal tickets

Receipt

POS sends this structure as a response to the paymentProcessed(...) method. It carries info for generating the receipt.

Property	Type	Required	Description
receiptInfo	ReceiptInfo	No	Object with properties containing information about the bill or the receipt.
items	ReceiptItem	Yes	Items printed on the receipt. If relevant, include the Payment, or any discount. The total amount on the receipt will be the sum of items prices.
taxInfo	TaxInfo	Yes	Calculated tax. TaxInfo is verified. Sum of all TaxInfo.base plus sum of all TaxInfo.vat must be equal to related Payment.total. If not equal, the related payment is canceled.
fiscalInfo	FiscalInfo	No	Fiscal reports such as czech EET and others
receiptDeliveryType	string	No	This parameter is used to determine whether the receipt is generated by Qerko, sent by email or will be received later via method getPostponedReceipt. Allowed values: `QERKO_GENERATED`, `EMAIL`, `POSTPONED`

Email addresses:

Sandbox: paymentId@receipts-sandbox.qerko.com
Production: paymentId@receipts.qerko.com.

ReceiptInfo

POS sends this structure as a part of the Receipt structure. It carries general info about the receipt. This object is treated as template data. Feel free to add any relevant info that the restaurant might want to print on the receipt. It will be possible to have a per-restaurant template in the future.

Property	Type	Required	Description
billName	string	No	The name of the bill
businessPremise	string	No	An identifier of the business premise
cashBox	string	No	An identifier of the cashbox
footerLines	string[]	No	Additional lines to print on the receipt below items.
headerLines	string[]	No	Additional lines to print on the receipt above items.
serial	string	No	Serial number or another identifier
timestamp	string	No	Timestamp in ISO 8601 (opens in a new tab) extended format
waiter	Waiter	No	The waiter who was serving the customer

ReceiptItem

POS sends this structure as a part of the Receipt structure. It carries info about an item to be printed on the receipt. This object is treated as template data. Feel free to add any relevant info that the restaurant might want to print on the receipt. It will be possible to have a per-restaurant template in the future.

Property	Type	Required	Description
name	string	Yes	The name of the item
quantity	string	No	The quantity of the item
price	string	Yes	The total price for the item(s)
taxName	string	No	The tax in which this item is included. Related to TaxInfo.name. As suggested here: Receipt (opens in a new tab)

Table

POS sends this structure in the list of tables as a response to the getTableList(...) method. It carries info about a table.

Property	Type	Required	Description
id	string	Yes	Identifier of the table.
name	string	No	Human readable name of the table. if not provided, id will be used instead. Example: `The table by the door`, or `Garden 1`
store	string	No	Identification of establishment for better filtering tables in restaurant-admin.
area	string	No	Identification of room for better filtering tables in restaurant-admin

TaxInfo

This structure is used as part of the Receipt structure. It carries info about tax.

Property	Type	Required	Description
name	string	No	Tax name. Related to ReceiptItem.taxName. As suggested here: Receipt (opens in a new tab) Example: `A`
rate	string	Yes	Tax rate percentage. Example: `15` means 15%, `12.5` means 12.5%, etc.
base	string	Yes	Tax base. Example: `100.00`
tax	string	Yes	Tax value. Example: `15.00`

Waiter

This structure is used as part of the Receipt structure. It carries info about a waiter, who has served the customer.

Property	Type	Required	Description
id	string	Yes	Identifier of the waiter. Unique in the restaurant.
name	string	Yes	Name of the waiter. Can’t be an empty string. Example: `John Doe`

Methods Error codes