Data structures

⚠️

Make sure that you allow Qerko to send additional properties in data structures. Otherwise your integration will become a blocker to progress Qerko further.

A list of data structures, which are used for data exchange between POS and Qerko. We provide JSON schemas for comfortable validation.

Bill

Bill structure is part of the getTableContents, getBill and payment methods.

Property	Type	Required	Description
`currency`	string	Yes	Used currency 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 POS. This identifier is used in 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	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 can make sense to deny splitting of the Bill in some scenarios, eg. a retail business. Default: `true`
`allowTip`	boolean	No	Can the customer add a tip? Default: `true`
`created`	string	No	Timestamp of the 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 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. Default: `false`
`denyMenus`	boolean	No	If `true` then Qerko will hide menus thus disable ordering. It is used internaly to prevent ordering to read-only Bills, such as retail business. 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 some.
`upcharges`	BillUpcharge[]	No	Unpaid upcharges on the bill. Default: `[]`

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
`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
`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.

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
`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)
`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`
`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.

BillUpcharge

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

CalculatedBillUpcharge

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

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

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.

🇭🇺 Hungary

Restaurant save username and password or token for the Szamlazz service in the Qerko Admin. POS returns required data for Szamlazz service and Qerko sends it to the Szamlazz service. Samlazz returns the receipt in PDF format and Qerko give it to the customer.

Property	Type	Required	Description
`qrData`	string	Yes	An utf-8 string data, which is 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	Informations for fiscal service.

Szamlazz

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

SzamlazzItem

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

SzamlazzSeller (optional)

Property	Type	Required	Description
`accountNumber`	string	No	For more info find “bankszamlaszam” in szamlazz doc. (1 - 128 length)
`issuerName`	string	No	For more info find “alairoNeve” in szamlazz doc. (1 - 255 length)
`message`	string	No	For more info find “emailSzoveg” in szamlazz doc. (1 - 255 length)
`name`	string	No	Name of item on invoice. For more info find “bank” in szamlazz doc. (1 - 255 length)
`replyToAddress`	string	No	For more info find “emailReplyto” in szamlazz doc. (valid email)
`subject`	string	No	For more info find “emailTargy” in szamlazz doc. (1 - 255 length)

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)

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
`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, then the sender does not expect the receiver to send a response.

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.
`calledMethod`	string null	No	Method which produced this response. Qerko sends this every time. 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

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
`currency`	string	Yes	Currency code in ISO 4217format.
`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.
`parts`	PaymentPart[]	Yes	This is an array which holds info for splitting the payment among payment providers.
`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. `REFUNDED` ‒ The payment is cancelled but it was paid-out to restaurant’s bank account in the past. It is the final state.
`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.
`additionalData`	any	No	Additional data from the Bill structure.
`discount`	Discount	No	Discount applied to the payment.
`upcharges`	CalculatedBillUpcharge[]	No	List of upcharges, which are paid by the payment.

PaymentOptions

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

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

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
`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.
`finalPrice`	string	No	The total final price for the bill. It can be skipped when POS wants to finalize the bill with the same price as it started (in most scenarios). But sometimes the POS needs to lower the final price (Gas station use-case). The Qerko then returns part of the authorized money to the customer. The final price must be equal or lower than the original price.
`fiscalInfo`	FiscalInfo	No	Fiscal reports such as czech EET, slovak UID, hungarian Szamlazz 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` - Qerko will generate the receipt from provided data * `POSTPONED` - Qerko will call getPostponedReceipt() method after a while * `EMAIL` - Qerko will expect the receipt via email as an attached document. See email addresses below this table. Supported attachments: `PDF`, `PNG`. * `EMAIL_HTML_BODY_AS_RECEIPT` - Qerko will expect the receipt via email. 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

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 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
`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

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
`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 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`

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

Methods Error codes