⚠️

Attention:

For fiscal compliance in Germany, Xentral POS provides a built-in solution. This guide is only relevant for countries like Austria or others where external integration with local fiscal services (e.g., fiskaly) is required. No additional partner integration is necessary in the German market.

Please have a look at the Xentral Helpcenter

Overview

This documentation describes how to integrate the KASSE POS system with third-party fiscalization services using webhooks. The POS itself does not communicate directly with any fiscalization provider (e.g., fiskaly). Instead, transactional events are emitted to a partner system that handles fiscalization and returns the final receipt metadata (including the QR code).

This approach ensures flexibility for country-specific requirements and allows external partners to manage compliance independently.

📘

Information:

Fiscalization is handled entirely by the integration partner. The POS emits events but does not communicate directly with fiskaly or other fiscal services.

---

Glossary

POS

Point of Sale system used for recording transactions and printing receipts.

Partner

External integration layer responsible for handling fiscalization processes and communicating with country-specific authorities or services.

e. g. Fiskaly

An example fiscalization service provider used in countries like Austria and Germany for TSE-compliant receipt finalization.

Webhook

A mechanism for POS to notify partner systems about completed transactions by sending HTTP POST requests.

Receipt QR Code

A machine-readable code returned by the partner after fiscalization, which is printed on the final receipt.

Fiscal Signature

A cryptographic string or token confirming that a receipt was signed according to local fiscal regulations.

Cash Register ID

Unique identifier assigned to a specific POS terminal instance.

TransactionCreated Event

JSON-based message emitted when a transaction is completed, used to inform the partner.

Bearer Token

A type of authentication token used in API calls for securing access.

Base64

An encoding format commonly used to embed binary data such as images in JSON payloads.

---

Getting Started

To integrate with the POS system:

• Have an active Fiskaly account (required for fiscalization).
• Setup a unique cashRegisterId.
• Register a webhook URL to receive transaction events.
• Ensure your backend exposes an HTTP POST endpoint to receive events of type
  com.xentral.pos.transactionCreated.v1.
  The payload structure is provided below.
• Return QR/fiscal data back to the POS.

⚠️

Attention:

The POS system delivers transaction data via HTTP POST webhook events. The partner is responsible for handling fiscalization and returning a QR code. This architecture is extendable for other countries.

---

POS Event Flow

Webhook: Transaction Created

When a sale is finalized at the POS, it triggers a transactionCreated event. This event is sent as an HTTP POST request to the configured partner webhook.

Event Name

com.xentral.pos.transactionCreated.v1

Example Payload

{
  "eventType": "SALE",
  "timestamp": "2025-04-09T10:33:48+02:00",
  "cashRegisterId": "POS1",
  "documentNumber": "400000",
  "lineItems": [
    {
      "productNumber": "1000000",
      "productName": "Regular",
      "taxRate": 0.19,
      "amount": 1,
      "discountPercent": 10,
      "currency": "EUR",
      "netPricePerProduct": 10,
      "totalGross": 10.71,
      "totalNet": 9,
      "totalTax": 1.71
    },
    ...
  ],
  "totalsByTaxRate": [...],
  "totals": {
    "totalNet": 31.8,
    "totalGross": 35.05,
    "totalTax": 3.25,
    "tip": 4.1,
    "currency": "EUR"
  },
  "payments": [
    {
      "paymentType": "CASH",
      "total": 35.05,
      "currency": "EUR"
    }
  ],
  "buyer": { ... },
  "seller": { ... },
  "shouldCreateQr": true
}

---

Receipt Submission to POS

After completing the fiscalization process, the partner must return QR or signature data to the POS via this endpoint.

Description:
The partner sends the generated QR code back to the POS system.

Request Body Example

{
  "cashRegisterId": "POS1",
  "documentNumber": "400000",
  "qrCode": "https://partner.example.com/qrcode/400000.png",
  "fiscalSignature": "base64signature==",
  "timestamp": "2025-04-09T10:34:10+02:00"
}

Notes

• The QR code may be a link or an embedded base64 string.
• This call must occur before the receipt is printed.

For full API reference, refer to the official POS API documentation.
Xentral API - cashier

---

Webhooks

If enabled, webhook payloads are signed using HMAC SHA-256.
Have a look at the Xentral API - Webhook

X-POS-Signature: sha256=...

Use the provided shared secret to validate the payload.