Skip to content
Last updated

Polling

Receiving events via Polling works as follows:

Query new order events

In order to receive new order events, the merchant Software Service must make requests on the polling endpoint regularly at a certain time interval, determined by Keeta. Whenever there is a new event the response will send the response code 200 with the list of events. If there are no new events, the response will send the response code 204.

IMPORTANT: It is important that the Software Service performs the requests within the timeframe determined by Keeta, as blocking and penalties may occur depending on the application's rules.

Keeta Polling Rate Limiting and Event TTL

  • The Keeta polling API enforces a rate limit of no more than two requests per minute per token. Once a request is blocked due to rate limiting, it will be allowed again in the next time window, which resets every minute.
  • It is recommended to poll for the latest order events associated with the token every 30 seconds. The TTL for order events is 4 hours and 10 minutes. In the Keeta system, orders automatically transition to a final state after 4 hours; an additional 10 minutes is provided as a buffer for time discrepancies.

Availability of new events in polling:

  • Keeta may have specific rules about the maximum time new events are available in polling before they are removed.
  • Always check with Keeta what the rules are for using the polling service.

Duplicate Events

  • Eventually Keeta may return the same event more than once, for example the CREATED event, including old orders. For this reason it is important that the Software Application handles the uniqueness of requests and events through id and the date.
  • When receiving an event, the Software Service must check the event id and validate that this event (id) has not been processed before. If this event has already been received previously, it must be discarded.

IMPORTANT: The Software Services should only accept a new order or update the status of an order after validating that the event has not been processed before.

It is also possible for the Software Service to make a request for the same event more than once (for example, requesting the POST /v1/orders/{orderId}/confirm endpoint repeatedly).

In these cases Keeta can handle this situation in two different ways:

  • As Keeta processes the requests synchronously, then Keeta should return HTTP 422, indicating that that event has been received before.

Acknowledgment Events

When receiving new events via Polling, the Software Service should always send acknowledgement so that Keeta does not send that same event again;

Important recommendations:

  • Merchants Software Service should make an acknowledgment request for each polling request with results.
  • If it receives events that are not used by the itself, it needs to send the acknowledgment of these events anyway so that it is not receiving them every polling again.
  • It is recommended that this be the default treatment for all events not yet mapped in the Software Service application.
  • The Software Services only needs to send acknowledgment of the event once.

IMPORTANT: Acknowledgment NOT apply for WEBHOOKS.