Frequently Asked Questions (FAQ)

This page collects the questions that come up most often when partners evaluate, demo, or roll out the fiskaltrust InStore App. It is intended for PosCreators, PosDealers, and fiskaltrust customer success teams. For step-by-step instructions, follow the links to the detailed guides in each answer.

API-level statements on this page follow the POS System API reference and the business case examples published on the fiskaltrust Development Platform.

Onboarding and Setup

Q: How does the setup of the InStore App work, step by step?

A: The setup consists of three parts: installing the app, pairing it with a CashBox, and configuring the device.

1. Install the app on the Android device. Use the installation guides for a manual APK install (stable or preview channel), the Google Play Store, or a partner device-management portal such as Orderman SystemCenterNext, the Sunmi Partner Portal, or the PAX stores.
2. Start the app and grant permissions. Enable Display over other apps when prompted, and allow Bluetooth if a Bluetooth printer is used.
3. Pair the app with a CashBox. In the fiskaltrust.Portal (sandbox or production), open Configuration > CashBox, select the CashBox, and generate a PIN for InStore App. The PIN is valid for five minutes. Enter it in the app and tap Pair. See Getting Started and Pairing InStore App.
4. Configure the device in the app settings: choose the Operation Mode (Consumer or Merchant), set a Terminal ID Filter when more than one device is connected to the CashBox, enable running in the background (mandatory on Android 15 and later), and set up the printer and the payment provider if needed.
5. Test. Use Print Demo and Test Communication in the settings, and, in a sandbox, the Dummy Payment Provider to run payments without a real payment provider.

Once paired, the app listens to the CashBox and displays receipts or starts payments as soon as the POS system triggers them. See the Available Settings page for all options.

Q: What are the prerequisites for using the InStore App on a device?

A: The following must be in place:

• An Android device with a touchscreen. An integrated or connected receipt printer is recommended for Consumer mode, but not required.
• A permanent and stable internet connection. The app receives its actions (show receipt, start payment) via push from the fiskaltrust backend.
• A CashBox in the fiskaltrust.Portal to pair with. For development and demos, use a sandbox CashBox. For the cloud-hosted POS System API, a Cloud CashBox is used; for local setups, the CashBox needs the corresponding helper (see PosSystem API Platforms).
• The Display over other apps permission, and Bluetooth for Bluetooth printers.
• Optionally, an account with a supported payment provider and, for software-based payment (SoftPOS), the provider's payment app installed on the same device.
• For digital receipts, complete master data in the fiskaltrust.Portal (outlet address and optional logo), as described in Digital Receipt preparations.

Q: Which devices are supported?

A: The InStore App runs on Android devices. It is designed for touch-enabled devices with an integrated thermal printer, but it also works with external printers via Bluetooth, USB, or ESC/POS network printing. Devices in common use include:

• Sunmi Android POS devices (deployable via the Sunmi Partner Portal).
• Orderman Android devices such as the Orderman10 (deployable via Orderman SystemCenterNext).
• PAX payment terminals (deployable via the PAX, Viva Wallet, or Global Payments stores).
• Generic Android tablets and smartphones, for example as a customer display next to a stationary POS or as a waiter's handheld running both the POS app and the InStore App.

Some payment providers also expose the terminal's integrated printer to the app (for example Shift4). On Android 15 and later, Enable running in Background must be switched on. If you plan to use a specific device model, contact fiskaltrust support to confirm printer and payment provider support for that model.

POS Integration

Q: Which requirements must a POS system meet to use the InStore App?

A: The POS system needs to be able to send HTTP/JSON requests to the fiskaltrust POS System API (v2). Every request carries the CashBox credentials from the fiskaltrust.Portal as headers (x-cashbox-id, x-cashbox-accesstoken, x-possystem-id) and a unique x-operation-id per operation so calls can be safely retried. The POS system should also be able to set a terminal identification (cbTerminalID in the request body, or the x-terminal-id header) so that requests reach the right device in multi-terminal setups.

No SDK, no device-side integration, and no direct network connection between the POS and the InStore App are needed. The app is paired with the CashBox and receives its actions from the fiskaltrust backend.

Q: Is a connection to the fiskaltrust POS System API sufficient?

A: Yes. All InStore App functionality is triggered through the POS System API: /pay starts a payment on the device, /sign fiscalizes the receipt, and /issue hands the receipt over to the InStore App for display, printing, or digital delivery. Which of these you use depends on the features you want (see For Developers).

For POS systems that are still integrated with the classic Middleware interface (/sign via IPOS v0 or the SignatureCloud API), receipts can also be shown in the InStore App without any POS change by activating the POS API Helper on the CashBox. See Existing fiskaltrust Integrations for the trade-offs.

Q: Is fiscalization through fiskaltrust required, or can the InStore App be used without it?

A: It depends on the feature:

• Payment can be used with or without fiskaltrust fiscalization. The /pay endpoint works independently of /sign, so a POS system can use the InStore App as its payment layer even in markets or setups where fiscalization is handled elsewhere. See Payment.
• Receipt display and digital receipts are driven by the /issue endpoint. In the standard flow, /issue takes the request and response pair returned by /sign, so the receipt is rendered from the fiscalized data. The API additionally defines a simple issue request in which the POS provides the receipt data itself, including the signature items produced by another fiscalization solution (see Receipt and Fiscalization). In both variants the receipt passes through the fiskaltrust.Middleware; a digital receipt cannot be created outside of it.

Q: How much integration effort is required for a POS system that is already connected?

A: This depends on the current integration:

• Already on the POS System API (v2): Low effort. Add /issue after /sign to show receipts on the InStore App, and /pay before /sign to process payments. Pass the same cbTerminalID on all calls and reuse the ftPayItems returned by /pay as cbPayItems in /sign. The business case examples on the Development Platform show the receipt requests for the individual scenarios (sale, refund, card payment, tips, and so on).
• On the classic IPOS v0 or SignatureCloud interface: Two options. Either activate the POS API Helper in the fiskaltrust.Portal to show receipts without any code change (no payment, no delivery status logging), or migrate to the POS System API v2 following the Migration Guide. The migration is mostly a change of base URL and headers plus a remapping of the ftReceiptCase, ftChargeItemCase, and ftPayItemCase values to the v2 values shown in the business case examples.

Existing fiskaltrust Integrations

Q: Do existing fiskaltrust integrations need to be adapted?

A: Not necessarily. For a pure receipt display, an existing /sign integration can be extended from the fiskaltrust.Portal by configuring the POS API Helper on the CashBox. The POS software stays unchanged, and every signed receipt is pushed to the paired InStore App.

Note that the POS API Helper does not log delivery statuses (scanned, acknowledged, printed). In Austria, this logging is required to prove compliance with the obligation to issue and accept receipts, so for production rollouts the /issue endpoint of the POS System API is the recommended path. Payment via the InStore App also requires the POS System API. See the Digital Receipt Implementation page for details.

Q: Which adaptations are typically required?

A: For a full integration on the POS System API v2, the typical changes are:

• Switch the base URL to the v2 endpoint and send the x-cashbox-id, x-cashbox-accesstoken, x-possystem-id, and x-operation-id headers.
• Call /issue with the /sign request and response pair after each signed receipt, and optionally poll the delivery status.
• Call /pay for electronic payments and take over the returned ftPayItems into cbPayItems. The returned pay items already carry the provider's transaction data in ftPayItemCaseData.
• Send a consistent cbTerminalID so that each request reaches the intended device.
• Implement idempotent retries: on a timeout, resend the same request with the same x-operation-id. For /pay, the result of an already started payment can be fetched via /PayResponse with the original operation ID.
• Respect the ftState flags of the receipt response. If the security mechanism is out of service, print a paper receipt instead of issuing a digital one. See Failure or disruption of internet connection.

Q: Can existing merchants activate the InStore App without major changes?

A: Yes. For a merchant whose POS is already fiscalized through fiskaltrust, the activation path is:

1. Check the master data of the outlet in the fiskaltrust.Portal (address, legal name, optional logo).
2. On a local CashBox, add and activate the POS API Helper, rebuild the configuration, and restart the Middleware. On a Cloud CashBox with the POS System API, no additional helper is required.
3. Install the InStore App on the device and pair it with the CashBox via PIN.
4. Configure printer and Terminal ID in the app.

Digital receipt bundles are ordered per CashBox in the fiskaltrust.Portal, see Bundles. No change to the POS software is needed for this receipt-only scenario.

Loyalty

Q: Can existing loyalty programs be connected?

A: There is no dedicated loyalty endpoint in the POS System API or the InStore App. Loyalty is treated as a business case on the receipt: the loyalty logic (verifying the program, earning or redeeming points) stays in the POS system or the loyalty provider's platform, and the result is reflected in the receipt data that the POS sends to fiskaltrust. The building blocks available today are:

• Receipt data: The pay item type "Loyalty Program/Customer Card" (ftPayItemCase) and the voucher pay item types represent points redemptions and customer card payments, cbCustomer identifies the consumer, and provider-specific loyalty data returned by a payment provider is carried in ftPayItemCaseData. The business case catalogue on the Development Platform describes the loyalty process (earn or redeem points, issue a receipt showing the updated balance) and contains payment examples in which the provider response includes loyalty transactions.
• Digital receipt: The receipt page can be shared into third-party apps, and receipts can be retrieved programmatically by receipt identifier, so a loyalty platform can import purchase data. See Delivery.
• InStore App idle screen: The app can show a merchant web page via the webview URL setting, for example a loyalty sign-up page.

If you need a specific loyalty integration, contact fiskaltrust to discuss the roadmap.

Q: Are there restrictions when choosing a loyalty provider?

A: No. Because fiskaltrust does not integrate a specific loyalty provider, the choice of provider is not restricted by the InStore App. The provider needs to be integrated by the POS system or use the digital receipt as its data source.

Q: Which interfaces are available for integrating loyalty solutions?

A: The interfaces available today are the POS System API receipt data (/sign and /issue, including cbCustomer, the loyalty and voucher pay item types, and ftPayItemCaseData), the digital receipt's share function and retrieval by receipt identifier, and the InStore App webview URL for merchant content. A dedicated loyalty API is not available.

Payment

Q: Is the InStore App required to use the payment functions?

A: Yes. fiskaltrust's payment integration is delivered through the InStore App. The app hosts the connection to the payment provider, either by driving a SoftPOS payment app installed on the same device (for example Softpay.io, GP tom, Viva, Worldline Tap on Mobile) or by talking to a hardware terminal (for example Hobex ECR or Shift4). The POS system only calls the /pay endpoint; the InStore App executes the payment on the device identified by cbTerminalID. See Payment and the PSP feature matrix.

Q: Can payments be processed independently of the InStore App?

A: Not through fiskaltrust. A POS system can of course keep its own direct payment provider integration and pass the payment result as cbPayItems (with the transaction data in ftPayItemCaseData) into /sign. Fiscalization and digital receipts work in the same way in that case; the business case examples for card payments on the Development Platform show the expected structure. Only the unified /pay endpoint and the provider independence it brings require the InStore App.

Q: Is there a central or single payment endpoint for the integration?

A: Yes. The /pay endpoint of the POS System API is the single entry point for all payment providers. A request contains:

• Action: payment, refund, cancel, or pre_authorization (not every provider supports every action).
• Protocol: use_auto to let fiskaltrust select the provider configured on the target device, use_first, use_all, use_none (asks the customer to select), or a provider-specific protocol.
• cbPayItem: the amount and a description.
• cbTerminalID: the device that should execute the payment.
• Optionally AcceptUnderPayment and AcceptOverPayment.

The response contains the selected Protocol, the ftQueueID, and the ftPayItems that were actually paid, including the provider's request and response data and the card receipt lines in ftPayItemCaseData. A running payment can be stopped with DELETE /pay, its state can be queried with /PeekPayRequestState, and its result can be fetched with /PayResponse using the original x-operation-id. The sandbox base URL is https://possystem-api-sandbox.fiskaltrust.eu/v2, the production base URL is https://possystem-api.fiskaltrust.eu/v2.

Q: What advantages does the InStore App offer in addition to a pure payment integration?

A: The main benefits are:

• Provider independence: The POS integrates /pay once. The payment provider is selected in the InStore App settings and can be changed without touching the POS software.
• One device for payment, customer display, and printing: Receipt display, QR code, email, SMS, and paper printing run on the same device as the payment, which reduces hardware at the POS.
• Linked payment and receipt data: The ftPayItems returned by /pay go straight into /sign, so the fiscal receipt and the digital receipt carry the payment details without manual mapping.
• Multi-terminal routing: Payments and receipts are routed to the right device via cbTerminalID, which supports mobile ordering, queue busting, and multiple checkouts on one CashBox.
• Compliance logging: Delivery statuses of digital receipts are logged, which is required in Austria and useful in Germany.
• Easy demos and testing: The Dummy Payment Provider in the sandbox lets you demonstrate and test the complete flow, including declines, timeouts, and tips, without a real payment provider.

Receipt and Fiscalization

Q: Where does the data for the digital receipt come from if no fiskaltrust fiscalization is used?

A: The receipt data always comes from the POS system through the POS System API. The InStore App has no receipt data source of its own. In the standard flow, fiskaltrust renders the receipt from the /sign request and response pair that the POS passes to /issue. For receipts that were fiscalized by another solution, the API defines a simple issue request: the POS sends the receipt itself (terminal ID, receipt reference, receipt moment, charge items, pay items, and the signature items from its own fiscalization, optionally header and footer lines) to /issue. The receipt is then stored and rendered by fiskaltrust like any other digital receipt. Contact fiskaltrust to confirm the availability of this variant for your market before relying on it.

Q: How is fiscalized receipt data provided for the receipt?

A: After /sign returns the signed receipt, the POS calls /issue with the receipt request and receipt response. Alternatively, /issue accepts the QueueId and QueueItemId of a receipt that was already signed. fiskaltrust stores the receipt document in the fiskaltrust.Cloud, returns ftQueueID, ftQueueItemID, and the DocumentURL to the POS, and pushes the receipt to the InStore App instances paired with the CashBox that match the terminal ID. The app then shows the receipt number, amount, and QR code and offers OK, Print, Email, and SMS. Every consumer action is logged. The POS can check whether the receipt was delivered via GET /issue/{QueueId}/{QueueItemId}/delivered, which returns 200 when delivered and 204 while still pending, or wait for the delivery with GET /BlockIssueRequest/{QueueId}/{QueueItemId}/WhileDelivered. Legacy POS API v0 integrations use the /print endpoint with the same request and response pair, as documented in the Introduction.

Q: Which data must the POS system provide?

A: At minimum, the receipt request must contain cbTerminalID, cbReceiptReference, cbReceiptMoment (in UTC), ftReceiptCase, the charge items (Quantity, Description, Amount, VATRate, ftChargeItemCase, Moment), and the pay items (Quantity, Description, Amount, ftPayItemCase). Card transaction details from the payment provider should be passed in ftPayItemCaseData so they appear on the receipt. Optional fields such as cbReceiptAmount, cbCustomer, cbUser, cbArea, additional receipt lines, and item lines improve the receipt. The merchant's address and logo come from the outlet master data in the fiskaltrust.Portal. See the mandatory fields for digital receipt visualization and the market-specific business case examples on the Development Platform for the correct case values.

Q: What role does fiskaltrust play in the receipt process without active fiscalization?

A: fiskaltrust acts as the receipt platform: it stores the receipt document tamper-proof in the fiskaltrust.Cloud, renders it as a tracking-free HTML page behind a unique HTTPS link, delivers it through the selected channel (QR code, print, email, SMS), logs the delivery status, and orchestrates the payment through the InStore App. The receipt still passes through the fiskaltrust.Middleware via /issue so that it can be delivered, even when the fiscal signature was created elsewhere or no signature is legally required.

For Developers

Q: Which APIs must be integrated for the InStore App?

A: Only the fiskaltrust POS System API (v2). There is no separate InStore App SDK. The relevant endpoints are /echo for the connectivity check, /pay for payments, /sign for fiscalization, and /issue for receipt delivery. /journal is used for exports and closings and is not InStore App specific. The request and response models are documented in the POS System API reference; ready-to-run receipt examples per market and business case are published on the Development Platform. For Android POS apps running next to the local Middleware, the same endpoints are also reachable via Android Intents.

Q: Which endpoints are relevant for Payment, Receipt, and Loyalty?

A:

Area	Endpoints	Notes
Payment	POST /pay, DELETE /pay, GET /PeekPayRequestState, POST /PayResponse	Action: payment, refund, cancel, pre_authorization. Protocol: use_auto or a provider-specific value. /PayResponse returns the result of a /pay call by x-operation-id.
Receipt	POST /sign, POST /issue, PUT /issue/{QueueId}/{QueueItemId}, GET /issue/{QueueId}/{QueueItemId}, GET /issue/{QueueId}/{QueueItemId}/link/qrcode, GET /issue/{QueueId}/{QueueItemId}/delivered	/issue takes the /sign request and response pair (or the queue item IDs) and returns the document URL. The PUT variant updates the delivery state with the actions accept, view, download, print, link, send (email, SMS, WhatsApp), or upload. The QR code call returns a PNG. The delivered call returns 200 once the consumer received the receipt.
Loyalty	No dedicated endpoint	Use cbCustomer, the loyalty and voucher pay item types, and ftPayItemCaseData in /sign, the digital receipt share function, and retrieval by receipt identifier.

Table 1. POS System API endpoints relevant for the InStore App.

Q: Which data flows exist between the POS system, the InStore App, and fiskaltrust?

A: A complete checkout consists of three flows:

1. Payment: The POS sends /pay with amount, protocol, and cbTerminalID to the POS System API. fiskaltrust pushes the payment action to the InStore App on the matching device, which starts the payment app or terminal. The result is returned to the POS as ftPayItems. If the POS loses the response, it queries /PayResponse with the same operation ID.
2. Fiscalization: The POS sends /sign with charge items and the pay items from step 1. The Middleware fiscalizes the receipt according to the market rules and returns the receipt response.
3. Issuing: The POS sends /issue with the request and response pair. fiskaltrust stores the receipt, returns the document URL, and pushes the receipt to the InStore App, which displays QR code, OK, Print, Email, and SMS. Consumer interactions are logged in the fiskaltrust backend, and the POS can poll the delivered status.

The InStore App never communicates with the POS directly. All communication runs through the fiskaltrust backend, and the terminal ID determines which device reacts.

Q: How can an existing integration be extended to support the InStore App?

A: Follow these steps:

1. If the integration still uses the v0 interface, migrate to the POS System API v2 according to the Migration Guide. Cloud CashBoxes work without extra configuration; local CashBoxes need the LocalPosSystemApi helper (see PosSystem API Platforms).
2. Pair an InStore App with a sandbox CashBox and select the Dummy Payment Provider.
3. Add the /issue call after each successful /sign and pass the same cbTerminalID. Verify that the receipt appears on the device.
4. Add the /pay call before /sign, pass the returned ftPayItems into cbPayItems, and implement the retry via /PayResponse. Test the special amounts of the Dummy Payment Provider for declines, timeouts, and tips.
5. Handle the ftState flags for out-of-service situations and print a paper receipt in that case.
6. Configure the Terminal ID Filter on each device according to the Multi-Terminal Setup rules, then switch to a production CashBox and a real payment provider.