Data structures
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 |
|---|---|---|---|
| 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 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. |
| upcharges | BillUpcharge[] | No | Unpaid upcharges on the bill. |
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. |
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 |
|---|---|---|---|
| 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 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 |
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. |
Hungary (work-in-progress)
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 |
|---|---|---|---|
| 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. |
| szamlazz | Szamlazz | Yes | 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 |
|---|---|---|---|
| name | string | No | Name of item on invoice. For more info find “bank” in szamlazz doc. (1 - 255 length) |
| accountNumber | string | No | For more info find “bankszamlaszam” in szamlazz doc. (1 - 128 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) |
| message | string | No | For more info find “emailSzoveg” in szamlazz doc. (1 - 255 length) |
| issuerName | string | No | For more info find “alairoNeve” in szamlazz doc. (1 - 255 length) |
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 4217format. |
| 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. |
| upcharges | CalculatedBillUpcharge[] | No | List of upcharges, which are paid by the payment. |
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_HTML_BODY_AS_RECEIPT |
| 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. |
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 |
| 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 |
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 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 |
PaymentOptions
POS sends this structure as a response to the paymentStart(…) 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 |