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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.