DocumentationWebhook interface

Webhook Interface

Available in API versionsv4

Disclaimer - This functionality is currently under development and is potential subject to change

Communication from POS to Qerko

Communication from POS to Qerko is facilitated through HTTP API, with full documentation present here (sandbox link)

Prerequisites for using the API

All API requests require an API key, which will be passed in Authorization: Bearer. In order to set up API key, don’t hesitate to contact Qerko for smooth integration with your POS system.

Important error status conventions

HTTP Status codeDescription
401Authentication error - i.e. wrong API key received
403Scope error - i.e. insufficient permissions to perform operation
400Validation error - received request body didn’t match prescribed schema. In such cases, behaviour of how Qerko treats requests isn’t specified

Communication from Qerko to POS

Communication from Qerko to POS driven by webhook, with configurable URL within our Administration. Compared to websocket API, it comes with easier implementation that requires no connection management. It should work for all cases, except when you for some reason cannot have publicly addressable webhook HTTP endpoint, for reasons such as networking.

Qerko will call configured webhook to transmit relevant events to POS, such as paymentStart from payment process, indicating that end user has started payment process. Webhook events also encode “requests” directed at POS to complete the flow of operations, such as getBill

Synchronous and Asynchronous responses

Webhook events transmitted from Qerko to POS can be handled in 2 possible ways.

  1. Asynchronous - POS takes note of an event and transmits further events to Qerko as response
  2. Synchronous - POS responds with relevant data in webhook HTTP response body

Motivation for asynchronous responses are situations where there are multiple trasmitted events by POS, related to single “request” from Qerko

Example: TBD

Support for asynchronous and synchronous responses is denoted in API reference by HTTP statuses, 202 for asynchronous and 200 for synchronous response

Asynchronous operations implementation

Asynchronous responses are sent to /reply endpoint, which is dedicated endpoint to receive events. Full flow described below

  1. Action of end user triggers event emitted to POS, by calling configured webhook
  2. Qerko sets internal timeout for 15 seconds to receive events. After 15 seconds the event is considered stale
  3. POS receives the event as HTTP request sent to configured webhook endpoint
  4. POS handles the event asynchronously, calling Qerko /reply endpoint
  5. Qerko processes the event from POS

Error handling

TBD

Webhook API reference

You can find schemas for your webhook implementation in api/v4 documentation (sandbox link)

Websocket interfaceMethods