From e30f603e672be6db63af9888f540370d4aaa3420 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 10:34:15 +0100 Subject: [PATCH 01/31] Refactor README for clarity and formatting consistency Updated the README to improve clarity and consistency in formatting. Adjusted section titles and descriptions for better readability. --- README.MD | 194 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 101 insertions(+), 93 deletions(-) diff --git a/README.MD b/README.MD index 5327090..16f8dce 100644 --- a/README.MD +++ b/README.MD @@ -3,148 +3,156 @@ ## Table of Contents - [Introduction](#introduction) - - [Running the howtos](#running-the-howtos) + - [Running the How-To's](#running-the-howtos) - [Before you continue - try it out](#before-you-continue---try-it-out) -- [Architecture and handling of multi terminal setups](#architecture-and-handling-of-multi-terminal-setups) - - [Component deployment](#component-deployment) - - [Payment Communication flow - terminalID based routing/filtering](#payment-communication-flow---terminalid-based-routingfiltering) - - [Payment Communication flow - protocol based routing/filtering](#payment-communication-flow---protocol-based-routingfiltering) -- [Debugging the communication](#debugging-the-communication) -- [Useful followup links](#useful-followup-links) +- [Architecture and Handling of Multi-Terminal Setups](#architecture-and-handling-of-multi-terminal-setups) + - [Component Deployment](#component-deployment) + - [Payment Communication Flow – terminalID-Based Routing and Filtering](#payment-communication-flow---terminalid-based-routingfiltering) + - [Payment Communication flow - protocol-Based Routing and Filtering](#payment-communication-flow---protocol-based-routingfiltering) +- [Debugging the Communication](#debugging-the-communication) +- [Related Links](#useful-followup-links) --- ## Introduction -We are focusing on running samples using the fiskaltrust InStore App and POS System API to get you up to speed fast. +This guide focuses on running samples using the **fiskaltrust InStore App** and the **POS System API** to help you quickly become familiar with them. -**NOTE:** As of today we only focus on integration related to the InStore App and the payment API. +**NOTE:** At this time, the scope is limited to integrations related to the **InStore App** and the **Payment API**. -### Running the howtos +### Running the How-To's -So far we only provide HOWTOs written in C#. To run them: +Currently, How-To's are provided in C# only. To run them, review the following: -- Take care to have installed `.NET 9` runtime and SDK -- Check the README in the HOWTO you want to use to check for any prerequisites to successfully use that HOWTO -- (optional) Visual Studio or Visual Studio Code for easier handling of the projects/solutions -- when using Visual Studio - - open the solution file in the HOWTO you want to open and run -- when using Visual Studio Code (VS Code) - - VS Code debug config should already be in place so do choose the HOWTO to debug from the debug target dropdown in the "RUN AND DEBUG" view -- alternatively on the command line - - open a terminal window and navigate to the HOWTO's directory you want to run - - type: `dotnet run` +**Prerequisites** +- Install the `.NET 9` runtime and SDK. +- Review the How-To that you want to run for any additional prerequisites. +- (Optional) Use Visual Studio or Visual Studio Code for easier project and solution handling. -### Install and configure the InStore App +**Using Visual Studio** +- Open the solution file of the How-To that you want and run it. -- InStore App is [installed](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/installation-guides) and connected to a CashBox via your fiskaltrust sandbox portal -- the HOWTO(s) use environment variables for configuration (read via the used libPosSystemAPI further discussed in HOWTO 01) - - `FISKALTRUST_CASHBOX_ID` - can be found in your fiskaltrust portal when configuring the CashBox - - `FISKALTRUST_CASHBOX_ACCESS_TOKEN` - can be found in your fiskaltrust portal when configuring the CashBox - - `FISKALTRUST_POS_SYSTEM_API_URL` - default is `https://possystem-api-sandbox.fiskaltrust.eu/v2` - - `FISKALTRUST_POS_SYSTEM_ID` - required for production use - For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal. - Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding. -- A payment provider is [configured](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) +**Using Visual Studio Code (VS Code)** +- A debug configuration is already provided. +- Select the How-To to debug from the debug target dropdown in the "Run and debug" view. -#### Using the `Dummy Payment Provider` for easier integration (InStore App Developer Mode) +**Using the Command Line** +- Open a terminal and navigate to the How-To directory that you want to run. +- Execute the following command: `dotnet run`. -IMPORTANT: This feature is available with InStore App v1.2.8-rc1 and newer. +### Installing and Configuring the InStore App -The InStore App supports a developer mode. When active a hidden `Dummy Payment Provider` can be configured that allows easy integration and testing of different payment success and error scenarios without the need to have any actual functioning payment provider access. +Install and configure the InStore App as follows: -How to enable: -- Enable the Developer Mode in the InStore App - - Start the InStore App so that you see the home screen - - At the bottom touch 5 times on the fiskaltrust logo so that the Developer Mode PIN Entry dialog opens - - Enter the PIN `4242` - - When successful an info dialog opens that the developer mode is now enabled and the app will exit after OK. -- Configure the `Dummy Payment Provider` - - Start the InStore app (again). - - Open the Settings and navigate to the "Payment settings" section - - Touch on the "Payment entry" (the first one in the "Payment Settings") and select the `Dummy Payment Provider` which is now visible because the developer mode is active. +- [Install](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/installation-guides) **InStore App** and connect it to a CashBox via your **fiskaltrust** sandbox portal. +- The How-To's use the following environment variables for configuration: + - `FISKALTRUST_CASHBOX_ID`: found in your **fiskaltrust** portal when configuring the CashBox. + - `FISKALTRUST_CASHBOX_ACCESS_TOKEN`: found in your **fiskaltrust** portal when configuring the CashBox. + - `FISKALTRUST_POS_SYSTEM_API_URL`: the default value is `https://possystem-api-sandbox.fiskaltrust.eu/v2`. + - `FISKALTRUST_POS_SYSTEM_ID` - required for production use. For production usage and release testing, you must use a valid POS System ID issued by **fiskaltrust**. You can obtain this ID by adding/registering a POS System in the **fiskaltrust** portal. For more information about the POS System registration, see [PosDealer Onboarding](https://docs.fiskaltrust.eu/docs/poscreators/get-started#3-posdealer-onboarding). +- [Configure](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) a payment provider. -How to use the `Dummy Payment Provider`: -- When executing a payment action with `use_auto` (or `test`) protocol payments will now be executed by the `Dummy Payment Provider` visible via the payment progress screen that appears when starting a payment action. -- Any amounts will result with SUCCESS response except the defined special amounts - - payment request for 30000,10 --> DECLINED - - payment request for 30000,20 --> TIMEOUT (returned as error message as no other option available yet) - - payment request for 30000,40 --> CANCELLED BY USER - - payment request for 30000,50 --> success with added guest tip - - payment request for 30000,60 --> success after 1min delay - - payment request for 30000,70 --> success after 3min delay - - payment request for 30000,80 --> success after 6min delay - - payment request for 30000,90 --> success but only 15000,50 will be approved +#### Using the Dummy Payment Provider for simplified integration (InStore App Developer Mode) -### Before you continue - try it out +IMPORTANT: This feature is available with InStore App v1.2.8-rc1 and later. -As a first step please check the [HOWTO 01 Payment readme](HOWTO_01_Payment_csharp/README.MD) on how to get the initial setup running. -When your setup works please continue here to get a deeper understanding and and check out the other HOWTOs. +The InStore App supports a developer mode. When enabled, a hidden **Dummy Payment Provider** can be configured, allowing easy integration and testing of different payment success and error scenarios without requiring access to a real payment provider. To enable the developer mode in the InStore App, complete the following steps: -## Architecture and handling of multi terminal setups +1. Start the InStore App and navigate to the home screen. +2. At the bottom of the screen, tap the **fiskaltrust** logo five times to open the Developer Mode PIN entry dialog. +3. Enter the PIN: 4242. +4. If successful, an information dialog will appear confirming that Developer Mode is enabled. Tap OK to close the dialog; the app will then exit automatically. -SCENARIO: The following on a usual restaurant flow where the `POS user` is using a mobile device on which a POS app as well as the InStore App is installed. +**Configuring the Dummy Payment Provider** -### Component deployment +1. Start the InStore App. +2. Open **Settings** and navigate to the **Payment settings** section. +3. Tap on **Payment entry** (the first item in **Payment Settings**) and select the **Dummy Payment Provider**, which is now visible because the developer mode is active. -Below are 2 common scenarios how the InStore App is used. Others are of course possible and these only act as examples! +**Using the Dummy Payment Provider** -#### Restaurant - mobile ordering scenario +When executing a payment action with the `use_auto` or `test` protocol, payments will be processed by the Dummy Payment Provider, which is visible via the payment progress screen that appears when starting a payment action. -When using 2 devices your setup might look like this: +Any payment amount will return a SUCCESS response, except for the following defined special amounts: + +| **Payment request** | **Result** | +|---------------------|-----------------| +| 30000,10 | DECLINED | +| 30000,20 | TIMEOUT (returned as an error message as no other option is available yet) | +| 30000,40 | CANCELLED BY USER | +| 30000,50 | SUCCESS with added guest tip | +| 30000,60 | SUCCESS after 1-minute delay | +| 30000,70 | SUCCESS after 3-minute delay | +| 30000,80 | SUCCESS after 6-minute delay | +| 30000,90 | SUCCESS, but only 15000,50 will be approved | + +### Before You Continue – Try It Out + +As a first step, review the [HOWTO 01 Payment readme](HOWTO_01_Payment_csharp/README.MD) to complete the initial setup. Once your setup is working, continue here to gain a deeper understanding and explore the other How-To's. + +## Architecture and Handling of Multi-Terminal Setups + +**Scenario**: A typical restaurant workflow in which the POS user operates a mobile device running both the POS app and the InStore App. + +### Component Deployment + +The following are two common deployment scenarios for the InStore App. Other configurations are possible; these examples illustrate typical setups. + +#### Restaurant - Mobile Ordering Scenario + +When using two devices, a typical setup might as follows: ![](docs/diagrams/out/diagrams/possystemapi_payment_architecture/comp_deploy_restaurant_multi_device.svg) -#### Retail - customer receipt scenario +#### Retail - Customer Receipt Scenario -In this scenario the InStore App is installed on a separate Android device positioned next to the POS. +In this scenario, the InStore App is installed on a separate Android device positioned next to the POS. ![](docs/diagrams/out/diagrams/possystemapi_payment_architecture/comp_deploy_retail_customer_interface.svg) -### Payment Communication flow - terminalID based routing/filtering +### Payment Communication Flow – terminalID-Based Routing and Filtering -When using multiple devices it is important to [configure](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#terminal-id-filter) the `terminalID` in the InStore App settings so that each device does use its own, unique in the connected cashbox, terminalID: +When using multiple devices, configure the `terminalID` in the InStore App settings so that each device uses its own unique `terminalID` in the connected CashBox, as follows: ![](docs/images/instoreapp_settings_terminalID.png) -When executing requests from the POS it is essential to use the terminalID to route the request(s) to the intended target system. -Here is an example when a user (like a waiter) is using an Android smartphone (terminal 02) to operate the POS app on which also the InStore App is installed and a payment transaction is triggered: +When executing requests from the POS, it is essential to use the `terminalID` to ensure that each request is routed to the correct target system. + +**Example:** A waiter uses an Android smartphone (terminal 02) running the POS app, with the InStore App installed. When a payment transaction is triggered, the request is routed specifically to the InStore App instance associated with terminal 02. ![](docs/diagrams/out/diagrams/possystemapi_payment_architecture/payment_comm_flow.svg) -### Payment Communication flow - protocol based routing/filtering +### Payment Communication flow - protocol-Based Routing and Filtering + +In addition to the terminalID, payment requests are also routed and filtered based on the protocol specified in the request. The protocol corresponds to the [payment vendor configured](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) on the target device in the InStore App settings. -Besides the terminalID the payment requests are also routed/filtered based on their defined protocol defined in the request itself. -The protocol maps to the [configured payment vendor](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) used on the target device in the InStore App settings. -E.g., using `Viva Wallet SoftPay` maps to the protocol `viva_eft_pos_instore`: +**Example:** Using **Viva Wallet SoftPay** maps to the protocol `viva_eft_pos_instore`: ![](docs/images/instoreapp_settings_payment.png) -Message routing rules: +Review the following **message routing rules**: -- protocol == `use_auto`: If any payment vendor is configured the request gets accepted. -- protocol == specific protocol like `viva_eft_pos_instore`: The request will only be accepted if the payment vendor supporting this protocol is configured (here `Viva Wallet SoftPay`) +- `protocol == use_auto`: If any payment vendor is configured, the request gets accepted. +- `protocol == specific protocol` (e.g.,`viva_eft_pos_instore`): The request is only accepted if the payment vendor that supports this protocol is configured (in this example, **Viva Wallet SoftPay**). -## Debugging the communication +## Debugging the Communication -We suggest to use [mitmproxy](https://www.mitmproxy.org/) to put in between your solution and the POS System API to see exactly what requests are going back and forth. +It is recommended to use [mitmproxy](https://www.mitmproxy.org/) as an intermediary between your solution and the POS System API to inspect all requests and responses exchanged between them. For this, complete the following: -- Please see [mitmproxy.bat](mitmproxy.bat) on how to run it. -- Set `FISKALTRUST_POS_SYSTEM_API_URL` as described in HOWTO_Payment_01 to `http://localhost:8080/v2` (the address the mitmproxy will listen on when using the batch file to start it) +- Refer to [mitmproxy.bat](mitmproxy.bat) for instructions on how to run it. +- Set the `FISKALTRUST_POS_SYSTEM_API_URL` environment variable as described in **How-To #1 - Getting started with payment in C#** to `http://localhost:8080/v2`, which is the address the mitmproxy listens when using the batch file to start it. -Then all requests from the HOWTOs will go to the mitmproxy where you can view these and the mitmproxy will forward the requests to the POS System API (as configured in the batch file). +With this setup, all requests from the How-To's are routed through mitmproxy, where they can be inspected. mitmproxy then forwards the requests to the POS System API as configured in the batch file. ![](docs/images/mitmproxy.png) +## Related Links -## Useful followup links - -- The [POS System API docs](https://docs.fiskaltrust.cloud/apis/pos-system-api) - - [pay](https://docs.fiskaltrust.cloud/apis/pos-system-api#tag/pay) requests -- The [InStore App docs](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/instore-app/introduction) - - How to [install the InStore App](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/instore-app/installation-guides) on your device - - How to [setup the InStore App](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/instore-app/setup-guide) to work with your fiskaltrust environment - - For development it might make sense to use the [preview release](https://link.fiskaltrust.eu/downloads/instoreapp/preview) instead of the [stable release](https://link.fiskaltrust.eu/downloads/instoreapp/stable). -- Important readings to avoid setup errors - - [multiterminal setup](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/multiterminal-settings) and how to avoid duplicate transactions +- [POS System API documentation](https://docs.fiskaltrust.cloud/apis/pos-system-api) + - [Pay requests](https://docs.fiskaltrust.cloud/apis/pos-system-api#tag/pay) +- [InStore App](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/instore-app/introduction) + - [Installing the InStore App](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/instore-app/installation-guides) on your device + - [Setting up the InStore App](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/instore-app/setup-guide) to work with your **fiskaltrust** environment + - For development, it might be useful to use the [preview release](https://link.fiskaltrust.eu/downloads/instoreapp/preview) instead of the [stable release](https://link.fiskaltrust.eu/downloads/instoreapp/stable) +- Important reading to avoid setup errors + - [Multi-terminal setup](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/multiterminal-settings) - Learn how to avoid duplicate transactions From a7cc7028a8b1153f9f2a8d2964e61c84e53ad8cd Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 10:41:49 +0100 Subject: [PATCH 02/31] Fix capitalization and emphasize important note Corrected capitalization in the Table of Contents and emphasized the importance of the developer mode feature. --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 16f8dce..8551bfe 100644 --- a/README.MD +++ b/README.MD @@ -4,7 +4,7 @@ - [Introduction](#introduction) - [Running the How-To's](#running-the-howtos) - - [Before you continue - try it out](#before-you-continue---try-it-out) + - [Before you continue - Try It Out](#before-you-continue---try-it-out) - [Architecture and Handling of Multi-Terminal Setups](#architecture-and-handling-of-multi-terminal-setups) - [Component Deployment](#component-deployment) - [Payment Communication Flow – terminalID-Based Routing and Filtering](#payment-communication-flow---terminalid-based-routingfiltering) @@ -54,7 +54,7 @@ Install and configure the InStore App as follows: #### Using the Dummy Payment Provider for simplified integration (InStore App Developer Mode) -IMPORTANT: This feature is available with InStore App v1.2.8-rc1 and later. +**IMPORTANT**: This feature is available with InStore App v1.2.8-rc1 and later. The InStore App supports a developer mode. When enabled, a hidden **Dummy Payment Provider** can be configured, allowing easy integration and testing of different payment success and error scenarios without requiring access to a real payment provider. To enable the developer mode in the InStore App, complete the following steps: From c646054b0ea9a993c78b7a1fefbb4fe1e8b8acf1 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 10:44:22 +0100 Subject: [PATCH 03/31] Fix capitalization in README section headers --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 8551bfe..8d08f59 100644 --- a/README.MD +++ b/README.MD @@ -4,7 +4,7 @@ - [Introduction](#introduction) - [Running the How-To's](#running-the-howtos) - - [Before you continue - Try It Out](#before-you-continue---try-it-out) + - [Before You Continue - Try It Out](#before-you-continue---try-it-out) - [Architecture and Handling of Multi-Terminal Setups](#architecture-and-handling-of-multi-terminal-setups) - [Component Deployment](#component-deployment) - [Payment Communication Flow – terminalID-Based Routing and Filtering](#payment-communication-flow---terminalid-based-routingfiltering) @@ -49,7 +49,7 @@ Install and configure the InStore App as follows: - `FISKALTRUST_CASHBOX_ID`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_CASHBOX_ACCESS_TOKEN`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_POS_SYSTEM_API_URL`: the default value is `https://possystem-api-sandbox.fiskaltrust.eu/v2`. - - `FISKALTRUST_POS_SYSTEM_ID` - required for production use. For production usage and release testing, you must use a valid POS System ID issued by **fiskaltrust**. You can obtain this ID by adding/registering a POS System in the **fiskaltrust** portal. For more information about the POS System registration, see [PosDealer Onboarding](https://docs.fiskaltrust.eu/docs/poscreators/get-started#3-posdealer-onboarding). + - `FISKALTRUST_POS_SYSTEM_ID`: required for production use. For production usage and release testing, you must use a valid POS System ID issued by **fiskaltrust**. You can obtain this ID by adding/registering a POS System in the **fiskaltrust** portal. For more information about the POS System registration, see [PosDealer Onboarding](https://docs.fiskaltrust.eu/docs/poscreators/get-started#3-posdealer-onboarding). - [Configure](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) a payment provider. #### Using the Dummy Payment Provider for simplified integration (InStore App Developer Mode) From b5ea092f7ea1f735be23b648059d91ee8e8d22f5 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 10:47:27 +0100 Subject: [PATCH 04/31] Refine wording in deployment scenarios Corrected wording for clarity in deployment scenario section. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 8d08f59..f1cb9a8 100644 --- a/README.MD +++ b/README.MD @@ -100,7 +100,7 @@ The following are two common deployment scenarios for the InStore App. Other con #### Restaurant - Mobile Ordering Scenario -When using two devices, a typical setup might as follows: +When using two devices, the setup may be structured as follows: ![](docs/diagrams/out/diagrams/possystemapi_payment_architecture/comp_deploy_restaurant_multi_device.svg) From 0b1b7280570db79ad43c2b30b0f0983577b2fcb5 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 10:49:09 +0100 Subject: [PATCH 05/31] Clarify prerequisite review instructions in README Updated instructions for reviewing prerequisites in How-To's. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index f1cb9a8..3749bb1 100644 --- a/README.MD +++ b/README.MD @@ -26,7 +26,7 @@ Currently, How-To's are provided in C# only. To run them, review the following: **Prerequisites** - Install the `.NET 9` runtime and SDK. -- Review the How-To that you want to run for any additional prerequisites. +- Review the README in the How-To that you want to use for any additional prerequisites. - (Optional) Use Visual Studio or Visual Studio Code for easier project and solution handling. **Using Visual Studio** From 1d55419b88411b40c0d38d3228a177b450a05a68 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:01:13 +0100 Subject: [PATCH 06/31] Fix links in README for consistency --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 3749bb1..5fda792 100644 --- a/README.MD +++ b/README.MD @@ -88,7 +88,7 @@ Any payment amount will return a SUCCESS response, except for the following defi ### Before You Continue – Try It Out -As a first step, review the [HOWTO 01 Payment readme](HOWTO_01_Payment_csharp/README.MD) to complete the initial setup. Once your setup is working, continue here to gain a deeper understanding and explore the other How-To's. +As a first step, review the [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD) to complete the initial setup. Once your setup is working, continue here to gain a deeper understanding and explore the other How-To's. ## Architecture and Handling of Multi-Terminal Setups @@ -140,7 +140,7 @@ Review the following **message routing rules**: It is recommended to use [mitmproxy](https://www.mitmproxy.org/) as an intermediary between your solution and the POS System API to inspect all requests and responses exchanged between them. For this, complete the following: - Refer to [mitmproxy.bat](mitmproxy.bat) for instructions on how to run it. -- Set the `FISKALTRUST_POS_SYSTEM_API_URL` environment variable as described in **How-To #1 - Getting started with payment in C#** to `http://localhost:8080/v2`, which is the address the mitmproxy listens when using the batch file to start it. +- Set the `FISKALTRUST_POS_SYSTEM_API_URL` environment variable as described in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD) to `http://localhost:8080/v2`, which is the address the mitmproxy listens when using the batch file to start it. With this setup, all requests from the How-To's are routed through mitmproxy, where they can be inspected. mitmproxy then forwards the requests to the POS System API as configured in the batch file. From 3dd276dbdc1220de39c2955efa76bc9eb18e2d54 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:12:49 +0100 Subject: [PATCH 07/31] Refine README for payment HOWTO in C# Updated README with clearer instructions and formatting improvements. --- HOWTO_01_Payment_csharp/README.MD | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/HOWTO_01_Payment_csharp/README.MD b/HOWTO_01_Payment_csharp/README.MD index 77b14ae..a889bf3 100644 --- a/HOWTO_01_Payment_csharp/README.MD +++ b/HOWTO_01_Payment_csharp/README.MD @@ -2,27 +2,27 @@ ## Prerequisites -Install and configure the InStore app to execute payments (see main DevKit README for further details). +Install and configure the **InStore app** to execute payments. For more information, see the [Development Kit README](possystemapi-devkit +/README.MD). ## What to expect when running this HOWTO -All our howtos are reusing some code that is provided as a .NET Assembly/library in source and can be found in `../libPosSystemAPI/` directory. Please check it after trying out the HOWTOs to get a better understanding what it does under the hood and how it interacts with the POS System API. +All How-To's reuse code provided as a .NET assembly/library in source, which can be found in the `../libPosSystemAPI/` directory. After trying out the How-To's, reviewing this code is recommended to gain a better understanding of how it works under the hood and how it interacts with the **POS System API**. -The HOWTO demonstrates +This How-To demonstrates the following: -- initial credential reading and executing an `/echo` request to know if the fiskaltrust / POS System API backend is reachable (actually done by libPosSystemAPI) -- creates a `/pay` request with `action: payment` -- writes the result of that request to the console -- basic error handling (see next) +- Initial credential reading and executing an `/echo` request to verify that the **fiskaltrust POS System API** backend is reachable (handled by `libPosSystemAPI`). +- Creation of a `/pay` request with `action: payment`. +- Writing the result of the request to the console. +- Basic error handling as described in the following section. ## Errors to be handled -There are multiple critical issues to be handled nicely to avoid double payments or the loss of a payment. +Several critical error scenarios must be managed carefully to prevent double payments or loss of a payment. -### We were able to send the payment request but we were not able to receive the response +**Example:** A payment request is successfully sent, but the response cannot be received. Possible causes include: -- Because we lost internet connectivity while waiting -- Because we could not get the response in time (= http timeout waiting for the response which can be simulated by a device on which the payment gets executed looses internet connectivity during operation) -- ? +- Internet connectivity is lost while waiting for the response. +- The response is not received within the expected time frame (HTTP timeout), which can be simulated by a device losing internet connectivity during payment execution. -In all cases the solution is to resend the original request (with identical operation ID and request body). The backend will then return the final result. \ No newline at end of file +In all of these cases, the solution is to resend the original request using the identical operation ID and request body. The backend will then return the final result of the operation. From a86cbbdf9670870c9738d45e6634d1917454b089 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:16:21 +0100 Subject: [PATCH 08/31] Update link to Development Kit README in README.md --- HOWTO_01_Payment_csharp/README.MD | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/HOWTO_01_Payment_csharp/README.MD b/HOWTO_01_Payment_csharp/README.MD index a889bf3..b3ed927 100644 --- a/HOWTO_01_Payment_csharp/README.MD +++ b/HOWTO_01_Payment_csharp/README.MD @@ -2,8 +2,7 @@ ## Prerequisites -Install and configure the **InStore app** to execute payments. For more information, see the [Development Kit README](possystemapi-devkit -/README.MD). +Install and configure the **InStore app** to execute payments. For more information, see the [Development Kit README](https://github.com/fiskaltrust/possystemapi-devkit/blob/main/README.MD). ## What to expect when running this HOWTO From d89d335f81f8f050a21fbfc645efd96b66dbd890 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:19:48 +0100 Subject: [PATCH 09/31] Fix capitalization in 'How-To' section header --- HOWTO_01_Payment_csharp/README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HOWTO_01_Payment_csharp/README.MD b/HOWTO_01_Payment_csharp/README.MD index b3ed927..ad207b4 100644 --- a/HOWTO_01_Payment_csharp/README.MD +++ b/HOWTO_01_Payment_csharp/README.MD @@ -4,7 +4,7 @@ Install and configure the **InStore app** to execute payments. For more information, see the [Development Kit README](https://github.com/fiskaltrust/possystemapi-devkit/blob/main/README.MD). -## What to expect when running this HOWTO +## What to expect when running this How-To All How-To's reuse code provided as a .NET assembly/library in source, which can be found in the `../libPosSystemAPI/` directory. After trying out the How-To's, reviewing this code is recommended to gain a better understanding of how it works under the hood and how it interacts with the **POS System API**. From 41c6e9cebe8c3ccd219a696525e7bfa81cca9775 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:22:55 +0100 Subject: [PATCH 10/31] Revise README for fiskal signing instructions Updated language for clarity and consistency in README. --- HOWTO_02_fiskal_signing_csharp/README.MD | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/HOWTO_02_fiskal_signing_csharp/README.MD b/HOWTO_02_fiskal_signing_csharp/README.MD index a56cae9..8c7ab60 100644 --- a/HOWTO_02_fiskal_signing_csharp/README.MD +++ b/HOWTO_02_fiskal_signing_csharp/README.MD @@ -2,16 +2,15 @@ ## Prerequisites -Have the POS System API + Cashbox config set up and ready to go for fiskal signing. See [fiskaltrust documentation](https://docs.fiskaltrust.cloud/) for further details. +Ensure that the **POS System API** and CashBox configuration are set up and ready for fiscal signing. For more information, [fiskaltrust documentation](https://docs.fiskaltrust.cloud/). -## What to expect when running this HOWTO +## What to expect when running this How-To -All our howtos are reusing some code that is provided as a .NET Assembly/library in source and can be found in `../libPosSystemAPI/` directory. Please check it after trying out the HOWTOs to get a better understanding what it does under the hood and how it interacts with the POS System API. +All How-To's reuse code provided as a .NET assembly/library in source, which can be found in the `../libPosSystemAPI/` directory. After trying out the How-To's, reviewing this code is recommended to gain a better understanding of how it works under the hood and how it interacts with the **POS System API**. -The HOWTO demonstrates - -- initial credential reading and executing an `/echo` request to know if the fiskaltrust / POS System API backend is reachable (actually done by libPosSystemAPI) -- creates a `/sign` request to similate signing a receipt -- writes the result of that request to the console -- basic error handling +This How-To demonstrates the following: +- Initial credential reading and executing an `/echo` request to verify that the **fiskaltrust POS System API** backend is reachable (handled by `libPosSystemAPI`). +- Creation of a `/sign` request to simulate signing a receipt. +- Writing the result of the request to the console. +- Basic error handling. From 3ea73a95b40d151a82f8c235a5fb9508fedacbca Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:23:20 +0100 Subject: [PATCH 11/31] Clarify documentation reference in README Updated the README to clarify reference to fiskaltrust documentation. --- HOWTO_02_fiskal_signing_csharp/README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HOWTO_02_fiskal_signing_csharp/README.MD b/HOWTO_02_fiskal_signing_csharp/README.MD index 8c7ab60..fefe9c7 100644 --- a/HOWTO_02_fiskal_signing_csharp/README.MD +++ b/HOWTO_02_fiskal_signing_csharp/README.MD @@ -2,7 +2,7 @@ ## Prerequisites -Ensure that the **POS System API** and CashBox configuration are set up and ready for fiscal signing. For more information, [fiskaltrust documentation](https://docs.fiskaltrust.cloud/). +Ensure that the **POS System API** and CashBox configuration are set up and ready for fiscal signing. For more information, see the [fiskaltrust documentation](https://docs.fiskaltrust.cloud/). ## What to expect when running this How-To From f562f8738f30f3695e1749eb1d76dec3e3bc371e Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:24:04 +0100 Subject: [PATCH 12/31] Fix typo in README for fiscal signing --- HOWTO_02_fiskal_signing_csharp/README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HOWTO_02_fiskal_signing_csharp/README.MD b/HOWTO_02_fiskal_signing_csharp/README.MD index fefe9c7..7694c93 100644 --- a/HOWTO_02_fiskal_signing_csharp/README.MD +++ b/HOWTO_02_fiskal_signing_csharp/README.MD @@ -1,4 +1,4 @@ -# HOWTO 02 - Getting started with fiskal signing in C# +# HOWTO 02 - Getting started with fiscal signing in C# ## Prerequisites From c8a95156b393f74b457aff9d9b60300184e3472c Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:28:01 +0100 Subject: [PATCH 13/31] Revise README for clarity and consistency Updated the README to improve clarity and consistency in language, including changes to headings and bullet points. --- HOWTO_08_pay_sign_issue_csharp/README.MD | 25 ++++++++++++------------ 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/HOWTO_08_pay_sign_issue_csharp/README.MD b/HOWTO_08_pay_sign_issue_csharp/README.MD index c4209ce..70e8434 100644 --- a/HOWTO_08_pay_sign_issue_csharp/README.MD +++ b/HOWTO_08_pay_sign_issue_csharp/README.MD @@ -1,20 +1,19 @@ -# HOWTO 08 - Execute the 3 main actions - Payment - Sign - Issue in C# +# HOWTO 08 - Executing the three main actions: Payment, Sign, and Issue in C# ## Prerequisites -Have the POS System API + Cashbox config set up and ready to go for fiskal signing. See [fiskaltrust documentation](https://docs.fiskaltrust.cloud/) for further details. +Ensure that the **POS System API** and CashBox configuration are set up and ready for fiscal signing. For more information, see the [fiskaltrust documentation](https://docs.fiskaltrust.cloud/). -## What to expect when running this HOWTO +## What to expect when running this How-To -All our howtos are reusing some code that is provided as a .NET Assembly/library in source and can be found in `../libPosSystemAPI/` directory. Please check it after trying out the HOWTOs to get a better understanding what it does under the hood and how it interacts with the POS System API. +All How-To's reuse code provided as a .NET assembly/library in source, which can be found in the `../libPosSystemAPI/` directory. After trying out the How-To's, reviewing this code is recommended to gain a better understanding of how it works under the hood and how it interacts with the **POS System API**. -The HOWTO demonstrates - -- initial credential reading and executing an `/echo` request to know if the fiskaltrust / POS System API backend is reachable (actually done by libPosSystemAPI) -- Creating a dummy list of charge items -- Execute the following actions with ftPosAPIOperationRunner which is a helper class wrapping the retry logic - - `/pay` the charge items - - Generate the receipt info with `/sign` - - Deliver the receipt to the user via `/issue` -- Wait for receipt delivered status +This How-To demonstrates the following: +- Initial credential reading and executing an `/echo` request to verify that the **fiskaltrust POS System API** backend is reachable (handled by `libPosSystemAPI`). +- Creation of a dummy list of charge items. +- Executing the following actions using `ftPosAPIOperationRunner`, which is a helper class that wraps the retry logic: + 1. `/pay` the charge items. + 2. Generate the receipt information using `/sign`. + 3. Deliver the receipt to the user via `/issue`. +- Waiting for the receipt delivered status. From f41ee355e0680bd41963c6eaf8c4aaab6fb03b7f Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 11:43:06 +0100 Subject: [PATCH 14/31] Fix formatting of Payment Communication Flow section --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 5fda792..643a1ec 100644 --- a/README.MD +++ b/README.MD @@ -8,7 +8,7 @@ - [Architecture and Handling of Multi-Terminal Setups](#architecture-and-handling-of-multi-terminal-setups) - [Component Deployment](#component-deployment) - [Payment Communication Flow – terminalID-Based Routing and Filtering](#payment-communication-flow---terminalid-based-routingfiltering) - - [Payment Communication flow - protocol-Based Routing and Filtering](#payment-communication-flow---protocol-based-routingfiltering) + - [Payment Communication Flow - protocol-Based Routing and Filtering](#payment-communication-flow---protocol-based-routingfiltering) - [Debugging the Communication](#debugging-the-communication) - [Related Links](#useful-followup-links) From f7f76dc6e1f7dae751b26993263c3212c86eb784 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:16:30 +0100 Subject: [PATCH 15/31] Update VS Code debug instructions in README Clarify VS Code debug configuration instructions. --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 643a1ec..7c46419 100644 --- a/README.MD +++ b/README.MD @@ -33,8 +33,8 @@ Currently, How-To's are provided in C# only. To run them, review the following: - Open the solution file of the How-To that you want and run it. **Using Visual Studio Code (VS Code)** -- A debug configuration is already provided. -- Select the How-To to debug from the debug target dropdown in the "Run and debug" view. +- The VS Code debug configuration should already be set up. +- Then, choose the How-To to debug from the debug target dropdown in the "Run and debug" view. **Using the Command Line** - Open a terminal and navigate to the How-To directory that you want to run. From 4bb77e24c2cdab39d14809b52d9365a5450105ec Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:18:03 +0100 Subject: [PATCH 16/31] Modify command line usage heading in README Updated section heading for command line usage. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 7c46419..44ac53d 100644 --- a/README.MD +++ b/README.MD @@ -36,7 +36,7 @@ Currently, How-To's are provided in C# only. To run them, review the following: - The VS Code debug configuration should already be set up. - Then, choose the How-To to debug from the debug target dropdown in the "Run and debug" view. -**Using the Command Line** +**Using the Command Line (alternatively)** - Open a terminal and navigate to the How-To directory that you want to run. - Execute the following command: `dotnet run`. From ad8e5b225ed4204faf517a7091edb3a2ebf8f5a9 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:21:06 +0100 Subject: [PATCH 17/31] Update README with configuration details Clarify the configuration environment variables for the InStore App. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 44ac53d..993a179 100644 --- a/README.MD +++ b/README.MD @@ -45,7 +45,7 @@ Currently, How-To's are provided in C# only. To run them, review the following: Install and configure the InStore App as follows: - [Install](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/installation-guides) **InStore App** and connect it to a CashBox via your **fiskaltrust** sandbox portal. -- The How-To's use the following environment variables for configuration: +- The How-To's use the following environment variables for configuration, which are read via the `libPosSystemAPI` (as further explained in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD).”: - `FISKALTRUST_CASHBOX_ID`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_CASHBOX_ACCESS_TOKEN`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_POS_SYSTEM_API_URL`: the default value is `https://possystem-api-sandbox.fiskaltrust.eu/v2`. From 02982ed441a4835d98c19adcccb17b9b97325180 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:21:48 +0100 Subject: [PATCH 18/31] Fix typo in README regarding environment variables --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 993a179..f8b7479 100644 --- a/README.MD +++ b/README.MD @@ -45,7 +45,7 @@ Currently, How-To's are provided in C# only. To run them, review the following: Install and configure the InStore App as follows: - [Install](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/installation-guides) **InStore App** and connect it to a CashBox via your **fiskaltrust** sandbox portal. -- The How-To's use the following environment variables for configuration, which are read via the `libPosSystemAPI` (as further explained in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD).”: +- The How-To's use the following environment variables for configuration, which are read via the `libPosSystemAPI` (as further explained in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD): - `FISKALTRUST_CASHBOX_ID`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_CASHBOX_ACCESS_TOKEN`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_POS_SYSTEM_API_URL`: the default value is `https://possystem-api-sandbox.fiskaltrust.eu/v2`. From e778e94b6640199b7df6e9b7d5cb32d103b7fcf1 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:22:16 +0100 Subject: [PATCH 19/31] Fix formatting issue in README for environment variables --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index f8b7479..7d428a0 100644 --- a/README.MD +++ b/README.MD @@ -45,7 +45,7 @@ Currently, How-To's are provided in C# only. To run them, review the following: Install and configure the InStore App as follows: - [Install](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/installation-guides) **InStore App** and connect it to a CashBox via your **fiskaltrust** sandbox portal. -- The How-To's use the following environment variables for configuration, which are read via the `libPosSystemAPI` (as further explained in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD): +- The How-To's use the following environment variables for configuration, which are read via the `libPosSystemAPI` (as further explained in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD)): - `FISKALTRUST_CASHBOX_ID`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_CASHBOX_ACCESS_TOKEN`: found in your **fiskaltrust** portal when configuring the CashBox. - `FISKALTRUST_POS_SYSTEM_API_URL`: the default value is `https://possystem-api-sandbox.fiskaltrust.eu/v2`. From f0700f5d38b64fc78a88c11121e96154789f9246 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:24:24 +0100 Subject: [PATCH 20/31] Update header case for Dummy Payment Provider section --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 7d428a0..2adefc0 100644 --- a/README.MD +++ b/README.MD @@ -52,7 +52,7 @@ Install and configure the InStore App as follows: - `FISKALTRUST_POS_SYSTEM_ID`: required for production use. For production usage and release testing, you must use a valid POS System ID issued by **fiskaltrust**. You can obtain this ID by adding/registering a POS System in the **fiskaltrust** portal. For more information about the POS System registration, see [PosDealer Onboarding](https://docs.fiskaltrust.eu/docs/poscreators/get-started#3-posdealer-onboarding). - [Configure](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) a payment provider. -#### Using the Dummy Payment Provider for simplified integration (InStore App Developer Mode) +#### Using the Dummy Payment Provider for Simplified Integration (InStore App Developer Mode) **IMPORTANT**: This feature is available with InStore App v1.2.8-rc1 and later. From b904169f9d7af9ae72f027332bdc240e78758b43 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:27:45 +0100 Subject: [PATCH 21/31] Correct PIN format and restart app instruction Updated instructions for enabling developer mode and configuring the Dummy Payment Provider. --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 2adefc0..0bcba7d 100644 --- a/README.MD +++ b/README.MD @@ -60,12 +60,12 @@ The InStore App supports a developer mode. When enabled, a hidden **Dummy Paymen 1. Start the InStore App and navigate to the home screen. 2. At the bottom of the screen, tap the **fiskaltrust** logo five times to open the Developer Mode PIN entry dialog. -3. Enter the PIN: 4242. +3. Enter the PIN: `4242`. 4. If successful, an information dialog will appear confirming that Developer Mode is enabled. Tap OK to close the dialog; the app will then exit automatically. **Configuring the Dummy Payment Provider** -1. Start the InStore App. +1. Restart the InStore App. 2. Open **Settings** and navigate to the **Payment settings** section. 3. Tap on **Payment entry** (the first item in **Payment Settings**) and select the **Dummy Payment Provider**, which is now visible because the developer mode is active. From 9294f551b24bfb66eb36047bbb3a2587d34d85cf Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:33:44 +0100 Subject: [PATCH 22/31] Clarify deployment scenarios in README Rephrase deployment scenarios section for clarity. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 0bcba7d..3152bf1 100644 --- a/README.MD +++ b/README.MD @@ -96,7 +96,7 @@ As a first step, review the [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD ### Component Deployment -The following are two common deployment scenarios for the InStore App. Other configurations are possible; these examples illustrate typical setups. +Below are two common scenarios for the InStore App. While other configurations are possible, these examples represent typical setups. #### Restaurant - Mobile Ordering Scenario From 45fce465b5f14cce65174737b2f2327ca8f3394c Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:34:52 +0100 Subject: [PATCH 23/31] Update wording in restaurant mobile ordering scenario --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 3152bf1..9994aea 100644 --- a/README.MD +++ b/README.MD @@ -100,7 +100,7 @@ Below are two common scenarios for the InStore App. While other configurations a #### Restaurant - Mobile Ordering Scenario -When using two devices, the setup may be structured as follows: +When using two devices, the setup might be structured as follows: ![](docs/diagrams/out/diagrams/possystemapi_payment_architecture/comp_deploy_restaurant_multi_device.svg) From a5cff1a9e5abcf3619437698fab581892d07c38a Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:36:42 +0100 Subject: [PATCH 24/31] Add link for terminalID configuration in README Updated the README to include a link for configuring terminalID in the InStore App settings. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 9994aea..7371a06 100644 --- a/README.MD +++ b/README.MD @@ -112,7 +112,7 @@ In this scenario, the InStore App is installed on a separate Android device posi ### Payment Communication Flow – terminalID-Based Routing and Filtering -When using multiple devices, configure the `terminalID` in the InStore App settings so that each device uses its own unique `terminalID` in the connected CashBox, as follows: +When using multiple devices, [configure](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#terminal-id-filter) the `terminalID` in the InStore App settings so that each device uses its own unique `terminalID` in the connected CashBox, as follows: ![](docs/images/instoreapp_settings_terminalID.png) From 1693c90586b6980f782b171492d0f9cfd89e8f0d Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:43:21 +0100 Subject: [PATCH 25/31] Update example for terminalID usage in README Clarified example of using terminalID in POS requests. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 7371a06..92b633e 100644 --- a/README.MD +++ b/README.MD @@ -118,7 +118,7 @@ When using multiple devices, [configure](https://docs.fiskaltrust.eu/docs/poscre When executing requests from the POS, it is essential to use the `terminalID` to ensure that each request is routed to the correct target system. -**Example:** A waiter uses an Android smartphone (terminal 02) running the POS app, with the InStore App installed. When a payment transaction is triggered, the request is routed specifically to the InStore App instance associated with terminal 02. +**Example:** A user (e.g., a waiter) uses an Android smartphone (terminal 02) to operate the POS app, on which the InStore App is installed, and a payment transaction is triggered: ![](docs/diagrams/out/diagrams/possystemapi_payment_architecture/payment_comm_flow.svg) From 8e0877abfe21e3038212b145a74863696d6cd08e Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:46:25 +0100 Subject: [PATCH 26/31] Update README with protocol-based routing details Clarified the description of payment request routing and filtering based on the configured payment vendor. --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 92b633e..beff83b 100644 --- a/README.MD +++ b/README.MD @@ -124,13 +124,13 @@ When executing requests from the POS, it is essential to use the `terminalID` to ### Payment Communication flow - protocol-Based Routing and Filtering -In addition to the terminalID, payment requests are also routed and filtered based on the protocol specified in the request. The protocol corresponds to the [payment vendor configured](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) on the target device in the InStore App settings. +In addition to the terminalID, payment requests are also routed and filtered based on the protocol specified in the request. The protocol corresponds to the [payment vendor configured](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings) used on the target device in the InStore App settings. **Example:** Using **Viva Wallet SoftPay** maps to the protocol `viva_eft_pos_instore`: ![](docs/images/instoreapp_settings_payment.png) -Review the following **message routing rules**: +**Message routing rules**: - `protocol == use_auto`: If any payment vendor is configured, the request gets accepted. - `protocol == specific protocol` (e.g.,`viva_eft_pos_instore`): The request is only accepted if the payment vendor that supports this protocol is configured (in this example, **Viva Wallet SoftPay**). From 289718dd8b1e65d1db78b41c2c539f36a6909935 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 12:51:16 +0100 Subject: [PATCH 27/31] Clarify debugging instructions for mitmproxy usage Updated the debugging section to clarify the use of mitmproxy for inspecting requests and responses. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index beff83b..0ef90bd 100644 --- a/README.MD +++ b/README.MD @@ -137,7 +137,7 @@ In addition to the terminalID, payment requests are also routed and filtered bas ## Debugging the Communication -It is recommended to use [mitmproxy](https://www.mitmproxy.org/) as an intermediary between your solution and the POS System API to inspect all requests and responses exchanged between them. For this, complete the following: +It is recommended to use [mitmproxy](https://www.mitmproxy.org/) as an intermediary between your solution and the POS System API to see exactly which requests are being sent and received. For this, complete the following: - Refer to [mitmproxy.bat](mitmproxy.bat) for instructions on how to run it. - Set the `FISKALTRUST_POS_SYSTEM_API_URL` environment variable as described in [HOWTO_01_Payment](HOWTO_01_Payment_csharp/README.MD) to `http://localhost:8080/v2`, which is the address the mitmproxy listens when using the batch file to start it. From 497ad8ad5071f0dfc2e7c4084b32e500c4d89189 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 13:00:52 +0100 Subject: [PATCH 28/31] Fix formatting of action steps in README --- HOWTO_08_pay_sign_issue_csharp/README.MD | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/HOWTO_08_pay_sign_issue_csharp/README.MD b/HOWTO_08_pay_sign_issue_csharp/README.MD index 70e8434..d2d88f3 100644 --- a/HOWTO_08_pay_sign_issue_csharp/README.MD +++ b/HOWTO_08_pay_sign_issue_csharp/README.MD @@ -13,7 +13,7 @@ This How-To demonstrates the following: - Initial credential reading and executing an `/echo` request to verify that the **fiskaltrust POS System API** backend is reachable (handled by `libPosSystemAPI`). - Creation of a dummy list of charge items. - Executing the following actions using `ftPosAPIOperationRunner`, which is a helper class that wraps the retry logic: - 1. `/pay` the charge items. - 2. Generate the receipt information using `/sign`. - 3. Deliver the receipt to the user via `/issue`. + - `/pay` the charge items. + - Generate the receipt information using `/sign`. + - Deliver the receipt to the user via `/issue`. - Waiting for the receipt delivered status. From dc3255183312be97d0a9d9f28a890a15d6fa2159 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 14:37:29 +0100 Subject: [PATCH 29/31] Update terminal instructions in README Clarify instructions for opening a terminal window. --- README.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.MD b/README.MD index 0ef90bd..24284f5 100644 --- a/README.MD +++ b/README.MD @@ -37,7 +37,7 @@ Currently, How-To's are provided in C# only. To run them, review the following: - Then, choose the How-To to debug from the debug target dropdown in the "Run and debug" view. **Using the Command Line (alternatively)** -- Open a terminal and navigate to the How-To directory that you want to run. +- Open a terminal window and navigate to the How-To directory that you want to run. - Execute the following command: `dotnet run`. ### Installing and Configuring the InStore App From 73c94162b28320ecce89735db1b1e35fcf735711 Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 14:45:46 +0100 Subject: [PATCH 30/31] Fix formatting in README for Developer Mode instructions Correct formatting for instructions and improve clarity. --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 24284f5..8aed9b0 100644 --- a/README.MD +++ b/README.MD @@ -61,13 +61,13 @@ The InStore App supports a developer mode. When enabled, a hidden **Dummy Paymen 1. Start the InStore App and navigate to the home screen. 2. At the bottom of the screen, tap the **fiskaltrust** logo five times to open the Developer Mode PIN entry dialog. 3. Enter the PIN: `4242`. -4. If successful, an information dialog will appear confirming that Developer Mode is enabled. Tap OK to close the dialog; the app will then exit automatically. +4. If successful, an information dialog will appear confirming that Developer Mode is enabled. Tap OK to close the dialog. The app will then exit automatically. **Configuring the Dummy Payment Provider** 1. Restart the InStore App. 2. Open **Settings** and navigate to the **Payment settings** section. -3. Tap on **Payment entry** (the first item in **Payment Settings**) and select the **Dummy Payment Provider**, which is now visible because the developer mode is active. +3. Tap **Payment entry** (the first item in **Payment Settings**) and select the **Dummy Payment Provider**, which is now visible because the developer mode is active. **Using the Dummy Payment Provider** From f3e3b9b42cb7f528f1edd244b4aa6e6ef204030f Mon Sep 17 00:00:00 2001 From: deboragracio <63159404+deboragracio@users.noreply.github.com> Date: Wed, 11 Feb 2026 14:51:33 +0100 Subject: [PATCH 31/31] Fix formatting for message routing rules section Corrected formatting for message routing rules in README. --- README.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 8aed9b0..a4bbee9 100644 --- a/README.MD +++ b/README.MD @@ -132,8 +132,8 @@ In addition to the terminalID, payment requests are also routed and filtered bas **Message routing rules**: -- `protocol == use_auto`: If any payment vendor is configured, the request gets accepted. -- `protocol == specific protocol` (e.g.,`viva_eft_pos_instore`): The request is only accepted if the payment vendor that supports this protocol is configured (in this example, **Viva Wallet SoftPay**). +- protocol == `use_auto`: If any payment vendor is configured, the request gets accepted. +- protocol == specific protocol (e.g.,`viva_eft_pos_instore`): The request is only accepted if the payment vendor that supports this protocol is configured (in this example, **Viva Wallet SoftPay**). ## Debugging the Communication