Data structures
Follows 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 (baby 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. |
| eetBkp | string | No | Czech EET BKP |
| eetPkp | string | No | Czech EET PKP |
| eetFik | string | No | Czech EET FIK |
| eetModeLine | string | No | Czech EET Mode, example: EET Režim: běžný |
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.tipBrutto, or any discount. The total amount on the receipt will be the sum of items prices. |
| taxInfo | TaxInfo[] | Yes | Calculated tax. Tax info 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 or sent by email or will be received later via method getPostponedReceipt. Email addresses: Sandbox: <paymentId>@receipts-sandbox.qerko.com Production: <paymentId>@receipts.qerko.com. Allowed values: QERKO_GENERATED, EMAIL, POSTPONED |
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 |
LoyaltyCardAuthorizationRequest
Qerko sends this structure to the Loyalty Card Authority. It contains properties which are needed to authorize the loyalty card.
| Property | Type | Required | Description |
|---|---|---|---|
| requestId | string | Yes | Identifier of this request in GUIDv4 (opens in a new tab) format. |
| expiration | string | Yes | Expiration of the request in ISO8601 (opens in a new tab) extended format. If the request results in a PENDING state, this is the timestamp of the request expiration. The result won’t be accepted after this expiration. Example: 2019-04-13T00:22:57+01:00 |
| loyaltyCardInfo | object | Yes | Object with unspecified properties. Exact properties will depend on the configuration for the card brand. It carries data readable from the physical loyalty card. Example: { “number”: “1234 5678 9012” } |
| emails | string[] | Yes | A set of known and verified emails of the customer. Lower-cased and hashed using SHA1 for privacy reasons (GDPR). |
| language | string | Yes | A suggested language for the message in response. In ISO639-1 (opens in a new tab) format. |
| hmacKey | string | Yes | A string to be used as the HMAC key for signature. It must not leak to the customer in any form. See below. |
| callbackUrl | string | Yes | URL where to navigate the customer to successfully finish the request. Example (opens in a new tab) The Loyalty Card Authority has to add query parameters token and signature. Signature is SHA1 HMAC in hex encoding. Data is the token, hmacKey is provided. See above. Result url (opens in a new tab) |
LoyaltyCardAuthorizationResponse
Loyalty Card Authority returns this structure in the authorizeLoyaltyCard method or it is used as an argument for the loyaltyCardAuthorizationFinished method.
It contains the authorization result.
| Property | Type | Required | Description |
|---|---|---|---|
| requestId | string | Yes | Identifier of this request in GUID v4 (opens in a new tab) format. It was received in the LoyaltyCardAuthorizationRequest. |
| result | string | Yes | Enum: AUTHORIZED - final result - successfully authorized UNAUTHORIZED - final result - unsuccessful authorization PENDING - final result will be sent in the future |
| loyaltyCardToken | string | Yes | If result = PENDING Token is ignored If result = UNAUTHORIZED Token is ignored If result = AUTHORIZED Token must be a non-empty string. POS should recognize the customer based on this string. Example: “abc-123-foo-bar” |
| message | string | Yes | If result = PENDING Message contains instructions for the customer If result = UNAUTHORIZED Message contains the reason why is the request unauthorized If result = AUTHORIZED Message is ignored Example: “Check your email for verification link” |
IndividualAnswer
This structure represents an answered question.
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Identifier of the question. |
| boolean | boolean | No | Customer’s response to the question. Required if dataType of related IndividualQuestion = “boolean” |
| number | number | No | Customer’s response to the question. Required if dataType of related IndividualQuestion = “number” |
| string | string | No | Customer’s response to the question. Required if dataType of related IndividualQuestion = “string” |
IndividualBillData
This structure represents an individual bill. It is a composite of Bill structure with a description of the offered bonus and a set of questions which needs to be answered before payment.
| Property | Type | Required | Description |
|---|---|---|---|
| individualBill | Bill | Yes | Bill which contains items. Effect of the loyalty card should be applied. |
| description | string | No | Brief description of the individual offer. |
| questions | IndividualQuestion[] | No | Default: [] A set of questions which need to be answered before |