Methods

Method signatures use TypeScript syntax for documentation purposes.

POS Methods

Below is a list of methods which will be called by Qerko. POS must implement these methods. It is required for both communication techniques (long-polling and websocket) as techniques call these methods.

getBill

getBill(id :string, idCustomer :string|null) :Bill

Qerko requests the contents of the opened bill. This method gets called before payment.

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.

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.

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|null) :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.

Payment

paymentStart

paymentStart(payment :Payment) :null | PaymentOptions

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 we do not recommend that 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 with 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 for the cancel, because if you cancel 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.
• 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.
• INVALID_ITEM ‒ In case Qerko has sent invalid or unknown item. Qerko app will inform the customer that the item has been paid by someone else.
• 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.

calculateUpcharges (billId :string, items :BillItem[] )

This method allows POS to use upcharges with Qerko to apply service fee, etc.

It is not mandatory to integrate this method.

Qerko Methods

These methods are integrated on the Qerko side, so POS can call them.

getPayment

getPayment(idPayment :string) :Payment

This method is an equivalent for the GET payment REST endpoint and it returns details of a payment. This method is provided to resolve various situations when POS missed the paymentClosed(…) call. This way POS can retrieve info about payment at any moment.

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.

Equivalent to DELETE REST endpoint.

capturePayment

capturePayment(params: { paymentId :string; receipt: :Receipt }) :null

Capture the payment which was started in captureMode=manual mode. Be advised to specify uuid in the Method call request message so you can get a response in case of error.

Equivalent to POST payment/capture REST endpoint

Other

Error

Error(error :Error, uuid :string|null) :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 silence, but the interval may 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.