O.Z.O.R.A. Payments API (0.0.1)

Receives Stripe webhook events (e.g. checkout.session.completed, checkout.session.expired). Verifies the webhook signature, saves the event into the transaction record, and updates the transaction status.

This is a public endpoint — no JWT required. Called directly by Stripe servers. The request body must be raw (not parsed as JSON) for signature verification.

Browser-facing endpoint. Stripe redirects the customer here after a Checkout attempt. Retrieves the Checkout Session from Stripe, saves it into the transaction record and redirects the customer to {frontend_url}/check?ticket_nr=...&email=...&message=....

If the request cannot be verified plain-text error are returned.

This is a public endpoint - no JWT required.

Receives the SimplePay IPN callback after a payment is completed/confirmed. Saves the IPN data and status into the transaction record. Responds with the HMAC-SHA384 signature in the Signature header (required by SimplePay protocol).

This is a public endpoint — no JWT required. Called directly by SimplePay servers.

Browser-facing endpoint. SimplePay redirects the customer here after a payment attempt. Verifies the signature, decodes the SimplePay response, saves it into the transaction record (the backref event also becomes the transaction status unless the IPN has already arrived or the status is FINISHED) and redirects the customer to {frontend_url}/check?ticket_nr=...&email=...&message=....

If the request cannot be verified plain-text error are returned

This is a public endpoint — no JWT required.

Searches for a transaction by its integer ID. Returns at most one result.

This is a service endpoint — it is primarily called by the tickets service (via payments_client.js) during ID searches, using a service JWT that carries the original user's privileges. Direct user JWT calls are also accepted.

Requires the Priv payments_search permission. For service JWT calls, the permission is checked from servicePrivs (forwarded user privs). For direct user JWT calls, the permission is checked from privs.

Stornos a previously finished payment. Takes the original transaction id and always creates the reversing transaction

With refund option as false (or not sent) it is a storno: only the credit note is issued, no money is moved, - any payment method accepted.

With refund=true it also refunds the full original amount at the payment provider. Currently supported for SimplePay, Stripe and Teya.

Requires a logged-in staff user with the payments_refund privilege.

Initiates a payment for a ticket. A JWT is optional

The endpoint validates the requested payment code against the template's available payment options, creates a transaction record, and calls the payment provider (SimplePay or Stripe Checkout). Returns the redirect URL for the payment provider's hosted payment page.

Returns all transaction records associated with the given ticket ID, ordered by transaction ID ascending.

Requires the Priv payments_search permission.

Also requires ticket access via either Priv tickets_search_flags/years/events OR Priv tickets_get_flags/years/events (all three of whichever set). The ticket must match the user's allowed scope. Ticket access is verified via the tickets service.

Returns all transaction records associated with the given ticket ID, ordered by transaction ID ascending. Each transaction includes its log entries (ordered newest first) unless include_logs is set to false

This is a service endpoint - it can only be called by other microservices using a service JWT.

Queries the Teya POSLink API for the current status of one TEYA transaction and, when the terminal has reached a final state (SUCCESSFUL / FAILED / CANCELLED), records the result and (on success) advances the ticket. This is the on-demand fast path for the frontend.

Requires a logged-in staff user with access to the ticket (verified via the tickets service).

Returns the list of available payment options for a given ticket. The caller must provide the ticket_id, ticket_status, template, and optionally metas.

This is a service endpoint - it can only be called by other microservices using a service JWT.

Returns one transaction by its id with the same data the tickets service /get-ticket returns in its transactions array: the transaction fields, the id of its storno transaction if there is one and its log entries.

Permissions

Requires the Priv payments_search permission.

Returns the distinct non-null ticket IDs referenced by transactions.

This is a service endpoint - it can only be called by other microservices using a service JWT.

Searches for transactions using an array of sequential search steps. Each step has an action (extend, constrain or omit) and a search_fields object.

How the 'action' parameter works

The endpoint walks through the steps in order, maintaining a set of matched transactions. Each step modifies that set based on its action:

Inside a single step, multiple search_fields are combined with AND. The first step should always be an extend - constrain and omit only operate on an existing set, so using them first is a no-op.

Search fields

Permissions

Requires the Priv payments_search permission.