Data Structures

⚠️

Make sure you allow Qerko to send additional properties in data structures. Otherwise, your integration will block Qerko’s future progress.

Below is a list of data structures used for data exchange between the POS and Qerko. We provide JSON schemas for easy validation.

Bill

The Bill structure is used in the getTableContents, getBill, and payment methods.

Property	Type	Required	Description
`currency`	string	Yes	The currency used, in ISO 4217 format. All prices in this structure must use the same currency. Example: `CZK`
`id`	string	Yes	Unique identifier of the bill from the POS. This identifier is used in the payment structure when Qerko returns the whole or part of the bill to be paid. Default: `null`
`items`	BillItem[]	Yes	Unpaid items on the bill.
`additionalData`	any	No	The 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. Default: `null`
`allowPartialPayment`	boolean	No	Can the customer pay only a subset of the items? It may make sense to deny splitting the bill in some scenarios, e.g., in retail. Default: `true`
`allowTip`	boolean	No	Can the customer add a tip? Default: `true`
`created`	string	No	Timestamp of bill creation in ISO 8601 extended format. Example: `2019-04-13T00:22:57+01:00` Default: `null`
`denyDiscounts`	boolean	No	Whether Qerko can apply another discount. Set to TRUE if there is already an internally applied discount by the POS and other discounts are unwanted. This applies only to discounts provided by restaurant owners. Discounts paid by Qerko or third parties (e.g., breweries) are not affected. `false` ‒ Qerko can apply a discount `true` ‒ Qerko can’t apply a discount. Default: `false`
`denyMenus`	boolean	No	If `true`, Qerko will hide menus and disable ordering. Used internally to prevent ordering to read-only bills, such as in retail. Default: `false`
`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.
`name`	string	No	Name of the bill to be shown to the customer. If not provided, Qerko will try to generate one.
`upcharges`	BillUpcharge[]	No	Unpaid upcharges on the bill. Default: `[]`

BillDiscountOffer

The POS sends this structure as part of the Bill structure. It contains information about a discount offer from the POS, specifically from the restaurant. The customer will likely accept it unless they have a better offer from another source (loyalty program, Qerko, etc.).

Property	Type	Required	Description
`name`	string	Yes	Human-readable name. It will be visible on the receipt and in the Qerko app.
`percent`	string	Yes	Discount percentage value. Only percentage discounts are supported, as other types are difficult to handle when paying only part of the bill. Example: `5` means 5% discount, `7.5` means 7.5% discount.
`additionalData`	any	No	The 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 accepts the offer, you will receive it in Payment.discount.additionalData.

BillItem

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

Property	Type	Required	Description
`name`	string	Yes	Human-readable name of the bill item. It will be visible on the receipt and in the 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. Can be decimal or negative. Example: `5` (5✕ beer), `0.7` (child portion)
`additionalData`	any	No	The 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 the bill item. This value is returned by Qerko when the same bill item is used (fully or partially). In other words, the POS sends it in the bill structure and Qerko returns it in the payment structure.
`minQuantity`	string	No	Minimum payable quantity. Also defines quantity precision. Qerko will allow only multiples of minQuantity as split quantity. If minQuantity = 0, the item cannot be split. If quantity is divisible by minQuantity, Qerko will allow splitting; otherwise, the item will be passed through Qerko with unchanged quantity. Example: If minQuantity = 1 and quantity is integer, the item can be split into lower integer quantities. If minQuantity = 1 and quantity is decimal, the item cannot be split. Example: `0.001`, `1`,… Default: `1`
`tags`	string[]	No	Used for grouping or categorizing products, e.g., for loyalty programs or discounts. Values depend on the POS-Qerko configuration. Used in discount definitions, e.g., “10% off for coffee if a tag:dessert is ordered as well.” Example: `["burger", "beef", "meat"]`
`subItems`	BillSubItem[]	No	List of subitems 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. The price to pay is the sum of the BillItem price and all its subItems.

Property	Type	Required	Description
`id`	string	Yes	POS identifier of the bill subitem. This value is returned by Qerko when the same bill subitem is used. The POS sends it in the bill subitem structure and Qerko returns it in the payment structure.
`name`	string	Yes	Human-readable name of the bill subitem.
`price`	string	Yes	Price to be added to the BillItem in the application.

BillUpcharge

Property	Type	Required	Description
`id`	string	Yes	Unique identifier of the upcharge from the POS.
`name`	string	Yes	Human-readable name of the upcharge. It will be visible in the Qerko app. Example: `Service fee for drinks`
`type`	string	Yes	Options: `POS_CALCULATED`

ReceiptUpcharge

Property	Type	Required	Description
`id`	string	Yes	Unique identifier of the upcharge from the POS.
`name`	string	Yes	Human-readable name of the upcharge. It will be visible on the receipt. Example: `Service fee for drinks`
`price`	string	Yes	Total price for the bill upcharge. Price can be zero. Example: 110.00

CalculatedBillUpcharge

Property	Type	Required	Description
`id`	string	Yes	Unique identifier of the upcharge from the POS.
`price`	string	Yes	Total price for the bill upcharge. Price can be zero. Example: 110.00
`additionalData`	any	No	The 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

Discount

This structure is used as part of the Payment structure. It contains information about a discount applied to the payment. Splitting the discount among bill items is entirely up to the POS. The POS must include the discount in Receipt.taxInfo.

Property	Type	Required	Description
`name`	string	Yes	Human-readable text for the receipt.
`source`	string	Yes	The source of the discount: `POS` ‒ Discount from the POS, sent in Bill `QERKO` ‒ Discount from Qerko, Qerko will pay the costs `PROMO` ‒ Discount set up in web administration `LOYALTY` ‒ Discount set up in web administration as 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.
`additionalData`	any	No	If source=POS, this property will contain whatever data the POS sent in the BillDiscountOffer structure.

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 the Qerko server, it contains one of the Error codes or null. When the error occurs in the POS, it can have a special effect, which is defined by the respective method.

FiscalInfo

The POS sends this structure as part of the Receipt structure. It contains information 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. In the future, it will be possible to have a per-restaurant template. If you are implementing for a country not documented here, send us your requirements and we will make them the standard for that country in this document.

Property	Type	Required	Description
`footerLines`	string[]	No	Additional lines to print on the receipt below fiscal 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 fiscal parameters.

🇭🇺 Hungary

The restaurant saves the username and password or token for the Szamlazz service in the Qerko Admin. The POS returns the required data for the Szamlazz service, and Qerko sends it to Szamlazz. Szamlazz returns the receipt in PDF format, and Qerko provides it to the customer.

Property	Type	Required	Description
`qrData`	string	Yes	A UTF-8 string used to create a QR code for the lower part of the receipt.
`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.
`szamlazz`	Szamlazz	No	Information for the fiscal service.

Szamlazz

Property	Type	Required	Description
`items`	SzamlazzItem[]	Yes	Items (max 500)
`seller`	SzamlazzSeller	No	Details about the seller.

SzamlazzItem

Property	Type	Required	Description
`name`	string	Yes	Name of the item on the invoice. (1 - 255 characters)
`quantity`	string	Yes	For more info, see “mennyiseg” in Szamlazz documentation.
`unit`	string	Yes	For more info, see “mennyisegiEgyseg” in Szamlazz documentation. (1 - 16 characters)
`vat`	string	Yes	For more info, see “afakulcs” in Szamlazz documentation.
`vatValue`	string	Yes	For more info, see “afaErtek” in Szamlazz documentation.
`grossValue`	string	Yes	For more info, see “bruttoErtek” in Szamlazz documentation.
`netValue`	string	Yes	For more info, see “nettoErtek” in Szamlazz documentation.
`netUnitPrice`	string	Yes	For more info, see “nettoEgysegar” in Szamlazz documentation.
`comment`	string	No	For more info, see “megjegyzes” in Szamlazz documentation.

SzamlazzSeller (optional)

Property	Type	Required	Description
`accountNumber`	string	No	For more info, see “bankszamlaszam” in Szamlazz documentation. (1 - 128 characters)
`issuerName`	string	No	For more info, see “alairoNeve” in Szamlazz documentation. (1 - 255 characters)
`message`	string	No	For more info, see “emailSzoveg” in Szamlazz documentation. (1 - 255 characters)
`name`	string	No	Name of the item on the invoice. For more info, see “bank” in Szamlazz documentation. (1 - 255 characters)
`replyToAddress`	string	No	For more info, see “emailReplyto” in Szamlazz documentation. (valid email)
`subject`	string	No	For more info, see “emailTargy” in Szamlazz documentation. (1 - 255 characters)

Property	Type	Required	Description
`footerLines`	string[]	No	Additional lines to print on the receipt below fiscal 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 fiscal parameters.
`uid`	string	No	Slovakian unique identifier of the receipt (unikátny identifikátor pokladničného dokladu)

MethodCallRequest

The POS receives this structure (although it is called a request) in a response from the long-polling endpoint or via websocket. It requests the POS to call a method.

The POS can also send this structure via websocket to call a method on Qerko side.

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

MethodCallResponse

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

The POS can also receive this structure via websocket as a response to a preceeding call of a method on Qerko side.

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

Payment

The POS receives this structure for the 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
`currency`	string	Yes	Currency code in ISO 4217 format.
`id`	string	Yes	Identifier of the payment. Qerko generates it for every payment.
`idBill`	string	Yes	Identifier of the related bill.
`idCustomer`	string	Yes	Unique identifier of the customer who pays. Used for the loyalty program on the POS side. The POS can identify the user if there was a previous call to the pairCustomer method. Otherwise, the POS can track user activity, but the user remains anonymous.
`items`	BillItem[]	Yes	List of items paid by the payment.
`parts`	PaymentPart[]	Yes	Array holding info for splitting the payment among payment providers.
`state`	string	Yes	`STARTED` ‒ The payment process has just started `PROCESSING` ‒ The payment is being processed `PAID` ‒ The payment is paid. This is the final state `CANCELLED` ‒ The payment is cancelled. This is the final state. `REFUNDED` ‒ The payment is cancelled but was already paid out to the restaurant’s bank account. This is the final state.
`tipBrutto`	string	Yes	Tip for the restaurant personnel.
`tipNetto`	string	Yes	Qerko might take a tip commission, so this is the tip after commission subtraction. This depends on the agreement with the restaurant. The POS should show this value to the restaurant personnel.
`additionalData`	any	No	Additional data from the Bill structure.
`discount`	Discount	No	Discount applied to the payment.
`upcharges`	CalculatedBillUpcharge[]	No	List of upcharges paid by the payment.

PaymentOptions

The POS sends this structure as a response to the paymentStart(…) method in the special flow with a manual call to the capturePayment(…) method.

Property	Type	Required	Description
`captureMode`	string	No	Mode of the final confirmation. `auto` means Qerko finalizes the payment automatically, `manual` means the POS must call the `capturePayment` method to finalize the payment. Default: `auto`

PaymentPart

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

Property	Type	Required	Description
`provider`	PaymentProvider	Yes	The payment provider used for this payment part.
`total`	string	Yes	The amount paid using this payment provider.

PaymentProvider

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

Property	Type	Required	Description
`id`	string	Yes	Unique identifier of this payment provider.
`name`	string	Yes	Human-readable provider name. Example: `Qerko`, `A meal ticket, Ltd.`, `Some smart card, Ltd.`, etc.
`type`	string	Yes	Describes the type of transaction, so the POS can apply correct rules according to local laws. `CARD` - Online payment using card `BANK_TRANSFER` - Payment by bank transfer `INVOICE` - Exchange of funds based on an invoice `VOUCHER` - Includes vouchers, coupons, and other pre-paid types. `MEAL_TICKET` - Payment by meal tickets

Receipt

The POS sends this structure as a response to the paymentProcessed(…) method. It contains information for generating the receipt.

Property	Type	Required	Description
`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 item prices.
`taxInfo`	TaxInfo	Yes	Calculated tax. TaxInfo is verified. The sum of all TaxInfo.base plus the sum of all TaxInfo.vat must equal the related Payment.total. If not equal, the related payment is canceled.
`finalPrice`	string	No	The total final price for the bill. Can be omitted if the POS wants to finalize the bill with the same price as it started (in most scenarios). Sometimes the POS needs to lower the final price (e.g., gas station use-case). Qerko will then return part of the authorized money to the customer. The final price must be equal to or lower than the original price.
`fiscalInfo`	FiscalInfo	No	Fiscal reports such as Czech EET, Slovak UID, Hungarian Szamlazz, and others.
`receiptDeliveryType`	string	No	Determines whether the receipt is generated by Qerko, sent by email, or will be received later via the getPostponedReceipt method. Allowed values: * `QERKO_GENERATED` - Qerko will generate the receipt from provided data * `POSTPONED` - Qerko will call the getPostponedReceipt() method after a while * `EMAIL` - Qerko expects the receipt via email as an attached document. See email addresses below this table. Supported attachments: `PDF`, `PNG`. * `EMAIL_HTML_BODY_AS_RECEIPT` - Qerko expects the receipt via email. The email body will be used as the receipt document. See email addresses below this table. Default: `QERKO_GENERATED`
`receiptInfo`	ReceiptInfo	No	Object with properties containing information about the bill or the receipt.

Email addresses:

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

ReceiptInfo

The POS sends this structure as part of the Receipt structure. It contains general information 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. In the future, it will be possible to have a per-restaurant template.

Property	Type	Required	Description
`billName`	string	No	The name of the bill
`businessPremise`	string	No	Identifier of the business premise
`cashBox`	string	No	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 extended format
`waiter`	Waiter	No	The waiter who served the customer

ReceiptItem

The POS sends this structure as part of the Receipt structure. It contains information 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. In the future, it will be possible to have a per-restaurant template.

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

Table

The POS sends this structure in the list of tables as a response to the getTableList(…) method. It contains information 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, the id will be used instead. Example: `The table by the door`, or `Garden 1`
`store`	string	No	Establishment identifier for better filtering of tables in restaurant-admin.
`area`	string	No	Room identifier for better filtering of tables in restaurant-admin

TaxInfo

This structure is used as part of the Receipt structure. It contains information about tax.

Property	Type	Required	Description
`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`
`name`	string	No	Tax name. Related to ReceiptItem.taxName. As suggested here: Receipt Example: `A`

Waiter

This structure is used as part of the Receipt structure. It contains information about the waiter who 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`

Need help? If you get stuck or have questions, email us at techsupport@qerko.com—we’re here for you!

Methods Error codes