Methods
Method signatures use TypeScript syntax for documentation purposes.
POS Methods
These methods are integrated on the POS side, so Qerko can call them by sending a Method call request via WebSocket or long-polling.
getBill
getBill(id: string, idCustomer: string | null): BillQerko requests the contents of the opened bill. This method is called before payment.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Identifier of the bill. |
idCustomer | string null | Deprecated and currently always null. Identifier of the customer, for POS-side loyalty use. |
Return
Bill structure which holds information about the requested bill. The difference between getTableContents(…) and this method is that getTableContents(…) returns all bills on a table, but this method returns a single bill regardless of the table it is on.
Special error codes
| Code | Description |
|---|---|
BILL_CLOSED | Qerko has requested a closed bill. The app will inform the customer that the bill is closed. |
BILL_NOT_FOUND | Qerko sent an invalid id. The app will take the customer to the bill selection screen. |
getPostponedReceipt
getPostponedReceipt(idPayment: string): ReceiptQerko asks for a receipt when receiptDeliveryType in paymentProcessed is POSTPONED. If you don’t use this, you can skip this method.
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.
Parameters
| Parameter | Type | Description |
|---|---|---|
idPayment | string | Identifier of the payment. Corresponds to Payment.id. |
Return
This method returns a Receipt structure which holds data for the receipt. Feel free to postpone the receipt again. Qerko will retry for up to 24 hours, after which support will be notified.
getTableList
getTableList(): Table[]Qerko requests a list of tables in the restaurant. It is used to get data for pairing QR codes and tables on Qerko’s web.
Parameters
This function has no input parameters.
Return
A list of Table structures representing tables that are available in the restaurant.
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.
Parameters
| Parameter | Type | Description |
|---|---|---|
idTable | string | Identifier of the table whose contents are needed. |
idCustomer | string null | Deprecated and currently always null. Identifier of the customer, for POS-side loyalty use. |
Return
A list of Bill structures representing open bills on the table.
paymentStart
paymentStart(payment: Payment): null | PaymentOptionsQerko requests the POS to start and validate the new payment.
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.
We recommend locking related items (or the whole bill) so the restaurant cannot 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.
POS must verify the payment, especially prices.
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.
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 cancellation, because if you cancel in the next phase it will cause a bad user experience due to the blocking of the customer’s funds.
Parameters
| Parameter | Type | Description |
|---|---|---|
payment | Payment | The payment to validate. |
Payment.state MUST be “STARTED” at this moment.
Return
This method can return two options:
null- you will most likely want to use this, or- PaymentOptions in case you need to use a flow with manual call to capturePayment(…) method.
Special error codes
| Code | Description |
|---|---|
BILL_LOCKED | Waiter is operating with the bill. Customer should try payment later. |
BILL_CLOSED | Qerko has requested a closed bill. The app will inform the customer that the bill is closed. |
BILL_NOT_FOUND | Qerko sent an invalid id. The app will take the customer to the bill selection screen. |
INVALID_ITEM | Qerko sent an invalid or unknown item. The app will inform the customer the item is paid. |
INVALID_DATA | Qerko sent invalid data (e.g. unknown bill, item, price mismatch, etc.). The app will refresh. |
paymentProcessed
paymentProcessed(idPayment: string): ReceiptQerko informs POS about a finished payment and requests POS to generate info for the receipt, including 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 block, depending on the bank, card issuer, etc.
Parameters
| Parameter | Type | Description |
|---|---|---|
idPayment | string | Identifier of the payment. Corresponds to Payment.id. |
Return
This method returns a Receipt structure which holds data for the receipt.
paymentClosed
paymentClosed(idPayment: string, state: string): nullQerko 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, displaying a notification, playing a sound, or sending a notification to mobile waiters. This way, 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.
Parameters
| Parameter | Type | Description |
|---|---|---|
idPayment | string | Identifier of the payment. Corresponds to Payment.id. |
state | string | The final state of the payment. Corresponds to Payment.state. |
Return
Literally null.
calculateUpcharges
calculateUpcharges(billId: string, items: BillItem[]): CalculatedBillUpcharge[]This method allows POS to use upcharges with Qerko to apply service fees, etc.
This method is called only if you send Bill.upcharges. Otherwise it won’t be called.
Parameters
| Parameter | Type | Description |
|---|---|---|
billId | string | Identifier of the bill. |
items | BillItem[] | List of bill items to calculate upcharges on. |
Return
CalculatedBillUpcharge[] representing a list of calculated upcharges.
Qerko Methods
These methods are integrated on the Qerko side, so POS can call them by sending a Method call request via WebSocket or by calling the respective REST API endpoint.
cancelPayment
cancelPayment(idPayment: string): nullCancels the payment. Be advised to specify uuid in the Method call request message so you can get a response in case of error.
Equivalent to the DELETE REST endpoint.
Parameters
| Parameter | Type | Description |
|---|---|---|
idPayment | string | Identifier of the payment. Corresponds to Payment.id. |
Return
Literally null.
capturePayment
capturePayment(params: { paymentId: string; receipt: Receipt }): nullCaptures 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 the POST payment/capture REST endpoint.
Parameters
| Parameter | Type | Description |
|---|---|---|
paymentId | string | Identifier of the payment. Corresponds to Payment.id. |
receipt | Receipt | The receipt of the payment. |
Return
Literally null.
getPayment
getPayment(idPayment: string): PaymentThis method is equivalent to the GET payment REST endpoint and returns details of a payment. This method is provided to resolve situations when the POS missed the paymentClosed(…) call. This way, the POS can retrieve information about a payment at any moment.
Parameters
| Parameter | Type | Description |
|---|---|---|
idPayment | string | Identifier of the payment. Corresponds to Payment.id. |
Return
Payment structure with state either CANCELLED or REFUNDED. It depends on the state the payment was in before cancellation. If the payment was already paid out to the restaurant’s bank account, then it will switch to REFUNDED; otherwise, it will switch to CANCELLED.
Other Methods
These methods are integrated on both sides, so either side (Qerko or POS) can call them by sending a Method call request via WebSocket or long-polling.
error
Error(error: Error, uuid: string | null): nullThis method is used to report an error that has occurred 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 your log or process it as you wish.
Parameters
| Parameter | Type | Description |
|---|---|---|
error | Error | The error that has occurred. |
uuid | string null | UUID of the MethodCallResponse that caused the error. Null if not relevant or unknown. |
Return
Literally null.
noop
noop(): nullThis 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. Otherwise, the connection will be considered stalled and closed.
Note: api/v4 for webhooks does not implement this method.
Parameters
This function has no input parameters.
Return
Literally null.
Need help? If you get stuck or have questions, email us at techsupport@qerko.com—we’re here for you!