diff --git a/HOWTO_01_Payment_csharp/README.MD b/HOWTO_01_Payment_csharp/README.MD index 77b14ae..ad207b4 100644 --- a/HOWTO_01_Payment_csharp/README.MD +++ b/HOWTO_01_Payment_csharp/README.MD @@ -2,27 +2,26 @@ ## 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](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 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. diff --git a/HOWTO_02_fiskal_signing_csharp/README.MD b/HOWTO_02_fiskal_signing_csharp/README.MD index a56cae9..7694c93 100644 --- a/HOWTO_02_fiskal_signing_csharp/README.MD +++ b/HOWTO_02_fiskal_signing_csharp/README.MD @@ -1,17 +1,16 @@ -# HOWTO 02 - Getting started with fiskal signing in C# +# HOWTO 02 - Getting started with fiscal signing 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) -- 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. diff --git a/HOWTO_08_pay_sign_issue_csharp/README.MD b/HOWTO_08_pay_sign_issue_csharp/README.MD index c4209ce..d2d88f3 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: + - `/pay` the charge items. + - Generate the receipt information using `/sign`. + - Deliver the receipt to the user via `/issue`. +- Waiting for the receipt delivered status. diff --git a/README.MD b/README.MD index 5327090..a4bbee9 100644 --- a/README.MD +++ b/README.MD @@ -3,148 +3,156 @@ ## Table of Contents - [Introduction](#introduction) - - [Running the howtos](#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) + - [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 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 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. -### 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)** +- 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 `Dummy Payment Provider` for easier integration (InStore App Developer Mode) +**Using the Command Line (alternatively)** +- Open a terminal window 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, 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`. + - `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. Restart the InStore App. +2. Open **Settings** and navigate to the **Payment settings** section. +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. -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](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 + +Below are two common scenarios for the InStore App. While other configurations are possible, these examples represent typical setups. + +#### Restaurant - Mobile Ordering Scenario + +When using two devices, the setup might be structured 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](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) -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 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) -### 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) used 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: +**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 see exactly which requests are being sent and received. 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 [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. -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