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): Bill

Qerko 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): Receipt

Qerko 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 | PaymentOptions

Qerko 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): Receipt

Qerko 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): void

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, 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

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

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

Captures 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): Payment

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

This 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(): 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. 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? If you get stuck or have questions, email us at techsupport@qerko.com—we’re here for you!

Webhook interface Data structures