2.3.3. Configure TalerBarr#
The first time you open TalerBarr, the module checks whether a valid merchant configuration already exists. In a new installation, there is usually no saved configuration yet, so TalerBarr automatically redirects you to the configuration page, as shown below.
Initial TalerBarr configuration page shown when no merchant configuration is available yet.#
2.3.3.1. Configuration overview#
The configuration card stores all information that TalerBarr needs in order to talk to the GNU Taler Merchant backend. In practice, this is where you connect your Dolibarr instance with your merchant instance.
Fields on the configuration card are:
Taler Merchant URL
Taler currency alias, useful in testing setups where a test currency should map to the Dolibarr base currency. For example, this can be used when you want to pay with Kudos while your Dolibarr accounting is in EUR, CHF, or another official currency.
Username, the username of the Taler Merchant instance that you want to use
Password, for the username indicated above
Sync direction, described in Choose the synchronisation direction
Order sync timing (optional), described in Choose the order sync timing
Bank account, the Dolibarr bank account to which wire transfers will be linked
Default customer for Taler orders
When you create the configuration, TalerBarr requests an access token from the merchant backend. The flow is designed so that your password is not stored in Dolibarr in the usual way. The authentication request is performed from your browser, and Dolibarr only receives the resulting access token.
If your Taler Merchant backend is configured with multi-factor authentication, an additional verification screen appears. This flow is described in Two-factor authentication flow.
2.3.3.2. Choose the synchronisation direction#
The synchronisation direction defines which side acts as the main source of truth. This simplifies both operations and maintenance. Currently two directions are supported.
Dolibarr -> Taler Use this when Dolibarr is your main source of truth for products and sales orders, and you mainly want to receive payment, refund, and settlement status updates from the Taler side.
Taler -> Dolibarr Use this when you already have a Taler merchant instance and want the ERP side to receive and maintain the relevant business objects so that you can benefit from the workflow and reporting features that ERP systems normally provide.
The selected direction affects both inventory and order handling. It does not change the fact that payment information is still received from Taler.
Although TalerBarr does not prevent you from changing the configuration later, it is recommended to keep one synchronisation direction in use whenever possible. During development, changing directions was tested, but the transition proved to be a tricky case. For stability and data consistency, it is better to keep this setting unchanged once the system is in active use.
2.3.3.3. Choose the order sync timing#
When synchronising from Taler to Dolibarr, the module supports two operation models:
When order is created Dolibarr receives the order as soon as it exists on the Taler side.
When order is paid Dolibarr receives the order only after the customer has actually completed payment.
The second mode is useful for vending, kiosk, or quick-service setups where you do not want unpaid draft activity to be pushed into the ERP and stored there as unnecessary data.
2.3.3.4. Normal login flow#
Every configuration flow starts with the main configuration form. In the next picture you can see an example of a filled configuration.
Example of a filled TalerBarr configuration form.#
Before doing this, you should create the Dolibarr bank account that matches the account configured on the Taler merchant side. In the examples of this tutorial I use a bank account called Taler Tutorial Bank. Make sure to configure your bank account properly before saving the TalerBarr configuration.
For Dolibarr instructions on creating a bank or cash account, see Create a new account / cash.
As soon as you press Create, the configuration is verified. If something is wrong, an error message is shown. If your setup requires two-factor or multi-factor authentication, you are redirected to Two-factor authentication flow. If no additional verification is required, you are redirected to Module config and home page.
2.3.3.5. Two-factor authentication flow#
This case happens when your Taler Merchant backend is configured to work with multi-factor authentication. Because TalerBarr requests an access token instead of storing your password directly in Dolibarr, you may have to confirm your authorisation through one or more additional channels. The exact number and type of challenges depends on the configuration of the merchant backend. All information needed for the verification is shown on the screen that appears after the first configuration submission.
First, the verification screen appears. On this screen you select the method through which you want to confirm your identity. In the example below, two options are available: email and SMS.
Two-factor authentication screen with the available verification methods.#
After you select the method and press Send code, the request is sent to the Taler system. If the request succeeds, you see a confirmation message together with a new field where you can enter the received code.
Two-factor authentication screen after requesting the verification code.#
As soon as you have received and entered the code, press Verify code. An intermediate state is then shown while the verification is being processed, as shown in the next picture.
Two-factor authentication verification in progress.#
After this (in case verification is successful) you will be forwarded to next screen.
2.3.3.6. Module config and home page#
After a successful configuration check, the next screen is the configuration card screen.
TalerBarr configuration card shown after successful verification.#
This screen contains a short recap of your configuration.
After this, you can navigate to the home page by clicking on the top bar. On the home page, the module provides a small statistics section together with a short overview of product and order counts, configuration status, and information about the last synchronisation.
TalerBarr module home page with configuration and synchronisation overview.#
From there, continue with the next tutorials to learn how to work with Manage Inventory and Manage Orders.