Fiscal Integration (External Partner)
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

POS event flow showing transaction, partner handling, and QR code return.
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.
Updated 6 days ago