Events

Subject

The events are tied to an entity, specified by the subject field:

• A terminal. This is the most common case.
• A pre-aggregated stream of events. This is typically for integrators to receive all relevant events for their terminals. A stream needs to be specifically provisioned for an integrator, at which point the stream id is provided.

Types

Adding new event types is not considered a breaking change, so clients should either request only known event types with a filter or be prepared to ignore unknown types.

Terminal events (eu.npay.api.pos.v0.TerminalStatus)

Created on every status update from terminal. The data field contains a snapshot of the terminal status object as returned by the get terminal status endpoint.

Transaction events (eu.npay.api.pos.v0.Transaction)

Created on every state change to a transaction. The data field contains a snapshot of the common transaction object.

Listing events

The /event/list endpoint allows you to retrieve a list of events, either based on filters or continue from a previous page using a token. If no filter or next_token is provided, the API starts returning events from the current moment onwards for all available events.

Using filters

Provide a filter object to retrieve events matching specific criteria. This can be used either to start a stream of events where next_token is used for all subsequent calls, or called repeatedly to get new events by changing the filtering time window.

{
  "filter": {
    "time": {
      "gt": "2024-11-07T05:25:55Z"
    },
    "type": {
      "eq": "eu.npay.api.pos.v0.Transaction"
    },
    "subject": {
      "eq": "t-12345678"
    }
  }
}

• time: Filter by event timestamp. If time is not provided, events from the current moment onwards are returned.
  • lt: Less than
  • le: Less than or equal
  • gt: Greater than
  • ge: Greater than or equal
• type: Filter by event type. If type is not provided, all event types are returned.
  • eq: Equal to a specific type
  • in: Equal to any in the array
• subject: Filter by terminal ID. At least one subject must be provided or the call is rejected. Possible subject values are described above.
  • eq: Equal to a specific ID
  • in: Equal to any in the array

If you want to get continue from a previous response, but do not want to use the next_token parameter, you can set the time filter with gt parameter to the timestamp of the last event received. However, this is reliable only if there is only one subject, as events from multiple subjects are not always exactly ordered by time when received.

Using a token

Every call returns a next_token string that can be passed in to continue from the request. Providing a next_token keeps the same filtering criteria as the original request, but returns the next page of results. No filter object should be included when using a token. The limit and wait_seconds parameters are not contained in the pagination state, so they should be provided on every request and may be different in different requests.

Request

{
  "next_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

{
  "events": [
    {
      "id": "evt-01JPHYGPRMH9QRFS3M69SJW9SH",
      "source": "https://api.npay.eu/pos/",
      "specversion": "1.0",
      "subject": "t-1234567890",
      "time": "2024-11-07T05:25:55Z",
      "type": "eu.npay.api.pos.v0.Transaction",
      "data": {
        // Transaction data
      }
    }
  ],
  "next_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

• events: Array of event objects.
• next_token: Token for the next page.

Polling strategies

Long polling

Set wait_seconds to a positive value (e.g., 30-60 seconds). If no events match the filter, the API waits up to the specified time for new events before responding.

This is ideal for real-time monitoring, reducing unnecessary requests.

Short polling

Set wait_seconds to 0 or omit it. The API returns immediately with matching events or an empty list.

Use this for historical data or periodic checks.

Best practices

• Use long polling for real-time updates to minimize API calls.
• Handle next_token for pagination to avoid missing events.
• Events are ordered by timestamp; process them in order.
• Implement retry logic for transient errors.
• Monitor rate limits and adjust limit accordingly.