NewsContact

POS System API

Five endpoints. One fiscal state machine.

The POS System API drives each transaction through deterministic state transitions. Your POS sends one step at a time. The Middleware signs, chains and journals under each country's law behind the same endpoints.

Open the 2.1 referenceSign a Sandbox receipt

The five endpoints

  • /echo – Connectivity check on POS startupminimum
  • /pay – Electronic payment through the Middleware
  • /sign – Fiscalise under national rules, every transactionminimum
  • /issue – Deliver the receipt, digital or printable
  • /journal – Export audit data, closings and inspections

Two endpoints make a compliant integration. Three more complete the checkout.

Endpoints cover the fiscal lifecycle
5
Endpoints for a minimum integration
2
Headers on every request
4
Integration for all supported markets
1

THE API SURFACE

Compact by design.

The same five endpoints work in every supported market. Country-specific compliance lives in the CashBox configuration, not in a separate API surface.

End pointPurposeTypical use
/echoConnectivity and health check, verifies Middleware version and capabilitiesTest the connection on POS startup
/payExecute and monitor payment processing, including timeouts and payment-method allocationSettle an order with one or more payment methods
/signFinalise and fiscalise the receipt under national rules, signing and hash chainingProduce an audit-proof, country-compliant receipt
/issueGenerate the receipt output and update its delivery state, digital or printableHand the signed receipt to the customer
/journalRetrieve audit-relevant journal data and rangesDaily closings, audit exports, archive snapshots

WHEN THE NETWORK DROPS

Send it again. No receipt signs twice.

Shop networks fail, usually mid-transaction. The API is built for this: every request carries its own ID. If your POS never gets an answer and sends the same request again, the second call returns the result of the first one. No sale gets signed twice, no receipt gets numbered twice.

x-operation-id: 9f4e…c21a  # one UUID per logical operation, unchanged on retry

  • Completed once, returned again

    A repeated call with the same identifier returns the result of the original operation.

  • Still running, then waiting

    A retry during processing blocks until the original operation finishes, then returns its result.

  • Different body, rejected

    The same identifier with a changed request body returns 409 Conflict. Retries must send the exact original body.

AUTHENTICATION

Four headers. No login step.

The API is scoped to a CashBox. Credentials come from the fiskaltrust.Portal at CashBox creation and travel on every request. No token exchange, no session state.

request headers
x-cashbox-id:           <from the Portal>
x-cashbox-accesstoken:  <from the Portal>
x-possystem-id:         <your registered variant>
x-operation-id:         <fresh UUID per operation>
x-cashbox-id
Identifies the target CashBox. Issued in the Portal with the CashBox configuration.
x-cashbox-accesstoken
Authenticates the caller. Store securely on the POS side.
x-possystem-id
Identifies your registered POS system variant, issued when you register the variant in the Portal.
x-operation-id
Your idempotency key. Generate one UUID per logical operation and reuse the same value on every retry.

Your POS talks to one API. The API talks to whatever the country demands.

END TO END

One transaction, step by step.

Each call advances the transaction one state. The Middleware talks to the signing components and the fiskaltrust.Cloud. Your POS never calls a TSE, an RT or a smartcard directly.

  1. /echo

    Connect

    Verify connectivity, Middleware version and capabilities on startup.
  2. /pay

    Settle (optional)

    Process electronic payment with timeouts and method allocation. Cash skips this step.
  3. /sign

    Fiscalise

    The receipt is signed, chained and sealed under the national rules.
  4. /issue

    Deliver (optional)

    Output the receipt, digital or printable, and track its delivery state.
  5. /journal

    Export

    Pull audit-relevant data for closings, exports and inspections.

One handover, zero re-mapping: the ftPayItems array returned by /pay plugs directly into /sign as cbPayItems. The fiscal receipt links to the electronic payment without touching terminal data.

RUNS EVERYWHERE, VERSIONED PROPERLY

One request format. Every deployment.

The same v2 request format works against the cloud-hosted endpoint and the Local Middleware on Windows, Linux and Android. Deploy where your architecture demands, your integration stays unchanged.

  • Cloud endpoint
  • Local · Windows
  • Local · Linux
  • Local · Android

  • Semantic versioning

    Breaking changes arrive only in major versions. Non-breaking changes add fields without altering existing models.

  • Pin your major version

    Unversioned requests get the latest. Production integrations pin a major version and upgrade on their own schedule.

  • Two published references

    Version 2.1 is current, version 2.0 stays documented for running integrations. A migration guide covers the path from v0.

SELF-SERVE

Everything you need before a call.

Judge feasibility and fit on your own terms. The stack is documented, public and testable today.

FAQ

Straight from the documentation.

The answers below follow the documentation platform. The reference carries the full detail.

POS System API or Middleware, what is the difference?

The Middleware performs the fiscalisation, signing and journaling. The POS System API is the HTTP/JSON interface the Middleware exposes. Your POS never calls signing components directly.

Do I need a different integration per country?

No. The endpoints stay identical across markets. Country-specific behaviour comes from the CashBox configuration and the request data, not from a separate API surface.

Is a retry safe after a network timeout?

Yes. Repeat the request with the same x-operation-id and the same body. The Middleware returns the original result or waits for completion. A changed body returns 409 Conflict.

Where do the credentials come from?

The fiskaltrust.Portal issues x-cashbox-id and x-cashbox-accesstoken with the CashBox configuration, and x-possystem-id when you register your POS system variant.

Do I need /pay for every transaction?

No. Use /pay when electronic payments run through the Middleware. Cash transactions go straight to /sign. Required steps depend on the country rules and the business case.

Same integration for cloud and local?

Yes. The cloud endpoint and the Local Middleware on Windows, Linux and Android accept the same v2 request format. One integration runs against all of them without code changes.

Read the reference. Send a request.

The v2.1 reference carries every model, schema and error code. The quickstart on the developer page takes you to a signed sandbox receipt.

Open the v2.1 referenceRequest a developer talk

You talk to real people