Methods
Method signatures use TypeScript syntax for documentation purposes.
POS Methods
Below is a list of methods which can be called by Qerko. POS must implement these methods. It is required for both communication techniques (long-polling and websocket). Both techniques call these methods.
getBill
getBill(id :string, idCustomer :string) :Bill
Qerko requests the contents of the opened bill. This will be called very often because it is the main Qerko functionality.
Parameter | Type | Description |
---|---|---|
id | string | Identifier of the bill. |
idCustomer | string null | Identifier of the customer, who is at the table. For the loyalty program on the POS side. |
searchBill
searchBills(qrIdentifier :string, idCustomer :string) :Bill[]
Qerko requests a list of bills mapped to a QR code.
This method is used in directBill extension.
Parameter | Type | Description |
---|---|---|
qrIdentifier | string | Identifier of a QR code, which has been scanned by the customer. Example: “000001” |
idCustomer | string/null | Identifier of the customer, who is at the table. For loyalty program on the POS side. |
Special error codes
This section describes string values that can appear in potential Error.code, that have special meaning.
- QR_INVALID ‒ In case the QR identifier was not found.
Special error codes
This section describes string values that can appear in potential Error.code, that have special meaning.
- BILL_CLOSED ‒ In case Qerko has requested a closed bill. Qerko app will announce to the customer that the bill was closed and there is nothing to pay any more.
- BILL_NOT_FOUND ‒ In case Qerko has sent invalid id. Qerko app will take the customer to the bill selection screen.
getTableList
getTableList() :Table[]
Qerko requests a list of tables which are in the restaurant. All of them. It is used to get data for pairing QR codes and tables on Qerko’s web.
getTableContents
getTableContents(idTable :string, idCustomer :string) :Bill[]
Qerko requests a list of opened bills on the table. This will be called when the customer scans Qerko’s QR code, so we need to offer a list of bills, because the customer hasn’t subscribed to a bill yet. This will be called very often because it is the main Qerko functionality.
Parameter | Type | Description |
---|---|---|
idTable | string | Identifier of the table, which contents is needed. |
idCustomer | string null | Identifier of the customer, who is at the table. For the loyalty program on the POS side. |
Error
error(error :Error, uuid :string) :null
This method is used to report error, which has occured while processing a response from a method. It is provided mainly for development. Qerko will call it when there is an error while processing a MethodCallResponse. Just write it into a log or process it as you want.
Parameter | Type | Description |
---|---|---|
error | Error | The error that has occured. |
uuid | string null | UUID of the MethodCallResponse, which caused the error. null if not relevant or unknown |
Noop
noop() :null
This is an empty method used to keep the connection between Qerko and POS alive. It is called after 45 seconds of quiet now, but the interval can change in the future. The method itself does nothing, but it is important to break the silence and send the response with null as a result. Else the connection will be considered as stalled and closed.
paymentStart
paymentStart(payment :Payment) :null
Qerko requests the POS to validate the new payment. POS must verify the payment, especially prices. POS must check that all of the items, which are about to get paid, are still on the bill and that everything is ready to be paid.
Although you can process the tax reports in this phase. It is not very advisable because the customer can be short of funds and you will have to cancel the reports. This can happen quite often and you know the tax office…
We recommend locking related items so the restaurant can not manipulate them. Or at least visually mark them as there is a payment in progress. We also recommend setting a timeout after which the bill is automatically unlocked so it doesn’t get stuck in a locked state in case of connection issues etc.
Qerko waits 15 seconds for the response. If the response isn’t received, the payment will be canceled.
POS can cancel the payment by throwing any error.
Any error or missing answer will cancel the payment. Feel free to cancel the payment in this phase. This is the best phase to cancel the payment, because if you cancel it in the next phase it will cause bad user-experience due to the blocking of the customer’s funds.
Parameter | Type | Description |
---|---|---|
payment | Payment | The payment to validate. |
Payment.state MUST be "STARTED" at this moment.
Special error codes
This section describes string values that can appear in potential Error.code, that have special meaning.
- BILL_LOCKED ‒ Qerko app will announce that there is a waiter operating with the bill right now and suggest to the customer to try the payment afterwards.
- INVALID_DATA ‒ In case Qerko has sent invalid data (e.g. unknown bill, unknown item, price mismatch, etc.). Qerko app will try to refresh data and eventually try again.
paymentProcessed
paymentProcessed(idPayment :string) :Receipt
Qerko informs POS about finished payment and requests POS to generate info for receipt, this includes any tax related reports, etc.
If the payment fails in paymentStart(...) or on the payment gateway, this method can be skipped and paymentClosed(...) will be called without calling this method.
Qerko waits 15 seconds for the response. If the response isn’t received, the payment will be canceled.
POS can cancel the payment by throwing any error.
Any error or missing answer will cancel the payment. The customer’s funds have already been blocked in this phase. So it is not very user-friendly to cancel the payment now because it can take a few hours to revoke the blocation, depending on the bank, card issuer, etc.
Parameter | Type | Description |
---|---|---|
idPayment | string | Identifier of payment. Corresponds to Payment.id. |
paymentClosed
paymentClosed(idPayment :string, state :string) :null
Qerko announces to POS that the payment has reached its final state and it won’t change in the future. It is mandatory to check the state of the payment, otherwise the payment can’t be considered finished by the POS. If it has any other value than PAID
the payment is canceled.
In case the connection is randomly closed before this method announces the payment state, please use the getPayment(...) method to make sure the payment went through successfully.
POS can request cancellation, by REST endpoint or by calling cancelPayment(...).
We recommend printing a short summary for the payment, display notification, play a sound, send notification to mobile waiters. So that the restaurant personnel know about the payment as soon as possible. It is recommended to show the related table, items summary, tip and a hint whether the bill is paid partially or completely.
Do not forget to unlock related items, which have been locked in the paymentStart(...) phase.
Parameter | Type | Description |
---|---|---|
idPayment | string | Identifier of payment. Corresponds to Payment.id. |
state | string | The final state of the payment. Corresponds to Payment.state. |
getPostponedReceipt
getPostponedReceipt(idPayment :string) :Receipt
Qerko asks for receipt when receiptDeliveryType in paymentProcessed is POSTPONED.
When the receiptDeliveryType in the response is POSTPONED, Qerko will call this method every 20 seconds until receiptDeliveryType changes to QERKO_GENERATED or EMAIL. This could be used when the POS is not ready to either generate or send the receipt.
Parameter | Type | Description |
---|---|---|
idPayment | string | Identifier of payment. Corresponds to Payment.id. |
cancelPayment
cancelPayment(idPayment :string) :null
Cancels the payment. Be advised to specify uuid in the Method call request message so you can get a response in case of error. Limited to 3 hours from payment creation.
Parameter | Type | Description |
---|---|---|
idPayment | string | Identifier of payment. Corresponds to Payment.id. |
Card Authority Methods
Card authority has to implement these methods in order to be able to support the Loyalty cards extension
authorizeLoyaltyCard
authorizeLoyaltyCard(request :LoyaltyCardAuthorizationRequest) :LoyaltyCardAuthorizationResponse
Qerko asks the card authority to authorize a loyalty card. This method returns the AuthorizationResponse structure.
Parameter | Type | Description |
---|---|---|
request | AuthorizationRequest | Authorization request described in the data structures section. |
POS Loyalty Methods
POS has to implement these methods in order to be able to support to support the Loyalty cards extension
startIndividualBill
startIndividualBill(idBill :string, loyaltyCardToken :string, items :BillItem[], language :string) :IndividualBillData
Qerko asks POS to start a new individual bill from the original bill with the specified loyalty card with specified items. This method returns an IndividualBillData structure.
Parameter | Type | Description |
---|---|---|
idBill | string | Identifier of the original non-individual bill |
loyaltyCardToken | string | String which identifies the customer.It is the result of the card authorization. |
items | BillItem[] | Items which should be transferred to the new individual bill. The same structures as in the base document. |
language | string | A suggested language for questions in ISO 639-1 (opens in a new tab) format. |
Special error codes
This section describes string values that can appear in potential Error.code, that have special meaning.
INVALID_LOYALTY_CARD_TOKEN ‒ Qerko app will announce that the loyalty card is invalid and suggest to the customer to reauthorize it.
BILL_NOT_CUSTOMIZABLE ‒ Qerko app will announce that the loyalty card can not be used with this bill.
updateIndividualBill
updateIndividualBill(idIndividualBill :string, answers :IndividualAnswer[]) :IndividualBillData
Qerko has answers for questions from the previous set. POS should modify the individual bill accordingly and return a new individual bill with or without questions. This method returns an IndividualBillData structure.
Parameter | Type | Description |
---|---|---|
idIndividualBill | string | Identifier of the individual bill which should be modified with provided answers. Another set of questions may be returned. |
answers | IndividualAnswer[] | A set of answers for the actual set of questions. |
cancelIndividualBill
cancelIndividualBill(idIndividualBill :string) :null
Qerko asks POS to cancel the individual bill. This is because the customer has left the negotiation session. POS should return items to the original bill. POS doesn’t have to cancel the individual bill. After this call the app checks all bills on the table and if the individual bill is found, the customer is returned to the individual bill. Else if the original bill is found, the customer is returned to the original bill. Else the app shows a message “Your bill was closed” and the customer is returned to the QR scanning screen.
This covers the situation when Alice starts her individual bill meanwhile Bob pays the rest of the original bill. In this case the original bill is closed so there is no bill to which individual items should be returned.
Parameter | Type | Description |
---|---|---|
idIndividualBill | string | Identifier of the individual bill which should be cancelled and items should be returned to the original, non-individual bill. |
Call the waiter
callWaiter(idTable :string) :null
This extension has not yet been implemented by Qerko.
This allows the customer to call a waiter. The way of notifying the waiter is up to POS.
POS must implement these methods in order to be able to support this extension.
Parameter | Type | Description |
---|---|---|
idTable | string | The table which the waiter should go to. |
Qerko Loyalty Methods
Below is a list of methods which can be called by POS.
loyaltyCardAuthorizationFinished
loyaltyCardAuthorizationFinished(response :LoyaltyCardAuthorizationResponse) :null
REST-API alternative: POST /api/v2/card-authority/loyalty-card-authorization-finished - request body contains the LoyaltyCardAuthorizationResponse structure.
Card authority should call this method when the customer completes the authentication challenge and the authority has the final result. When called with response.result = PENDING then the response is treated as UNAUTHORIZED.
Parameter | Type | Description |
---|---|---|
response | LoyaltyCardAuthorizationResponse | Authorization response described in data structures section. |