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.
| 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. |
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.
| 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. |
Payment
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 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.
| 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. |
upcharge
This method allows POS to use upcharges with Qerko to apply service fee, etc.
It is not mandatory to integrate this method.
calculateUpcharges (billId :string, items :BillItem[] )
| Parameter | Type | Description |
|---|---|---|
| upcharges | CalculatedBillUpcharge[] | List of calculated upcharges. |
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.
| 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.
Equivalent to DELETE REST endpoint.
| Parameter | Type | Description |
|---|---|---|
| idPayment | string | Identifier of payment. Corresponds to Payment.id. |
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.
| 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 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.