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(idBill: string, idCustomer: string | null): BillQerko requests the contents of the opened bill. This method is called before payment.
Parameters
| Parameter | Type | Description |
|---|---|---|
idBill | 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. This method is required when the POS is not ready to either generate or send the receipt right away. If you don’t need this method, you can skip it.
When the receiptDeliveryType in the response is POSTPONED, Qerko will call this method until receiptDeliveryType changes to QERKO_GENERATED or EMAIL. Qerko sends the getPostponedReceipt request in intervals with exponential falloff (for instance 1 minute delay, followed by 2 minutes delay, followed by 4 minutes delay…)
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 ensure that every item being paid is still on the bill and ready for settlement.
We recommend locking the related items (or the whole bill) so the restaurant cannot change them. At minimum, clearly mark that a payment is in progress. Also set a timeout to unlock the bill automatically in case of connection issues.
POS must verify the payment, especially prices.
Although you can process tax reports in this phase, we do not recommend it. The customer may lack sufficient funds, forcing you to cancel the reports, which happens surprisingly often.
Qerko waits 15 seconds for the response. If it doesn’t arrive in time, the payment is canceled automatically.
The POS can cancel the payment by throwing an error. Any error or missing answer cancels the payment. Canceling here provides the best user experience; canceling later blocks the customer’s funds unnecessarily.
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 an authorized 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 it doesn’t arrive, the payment is canceled.
The POS can still cancel the payment by throwing an error. Keep in mind that the customer’s funds are already blocked at this stage, so any cancellation may take hours to release depending on the bank or card issuer.
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): voidQerko 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 using the REST endpoint or calling cancelPayment(…).
We recommend printing a short summary of the payment, displaying a notification, playing a sound, or alerting mobile waiters. That way the staff knows about the payment immediately. Include the table, item summary, tip, and whether the bill is paid partially or in full.
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
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
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
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
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
null.
Need help? Contact techsupport@qerko.com for assistance.