taler-docs

taler-merchant-manual.rst (81748B)

---

 ..
   This file is part of GNU TALER.
 
   Copyright (C) 2014-2023 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 3.0, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
 
 .. _taler-merchant-backend-operator-manual:
 
 Merchant Backend Operator Manual
 ################################
 
 
 Introduction
 ============
 
 About GNU Taler
 ---------------
 
 .. include:: frags/about-taler.rst
 
 
 .. _About-this-manual:
 
 About this manual
 -----------------
 
 This manual targets system administrators who want to install a GNU
 Taler merchant *backend*.
 
 We expect some moderate familiarity with the compilation and
 installation of Free Software packages. An understanding of cryptography
 is not required.
 
 .. _Architecture-overview:
 
 Architecture overview
 ---------------------
 
 .. index:: crypto-currency
 .. index:: KUDOS
 
 Taler is a pure payment system, not a new crypto-currency. As such, it
 operates in a traditional banking context. In particular, this means that in
 order to receive funds via Taler, the merchant must have a regular bank
 account, and payments can be executed in ordinary currencies such as USD or
 EUR.  Taler can also be used as a regional currency; for such scenarios, the
 Taler system also includes its own stand-alone bank.
 
 .. index:: frontend
 .. index:: back-office
 .. index:: backend
 .. index:: DBMS
 .. index:: PostgreSQL
 
 The Taler software stack for a merchant consists of four main components:
 
 -  A *frontend* which interacts with the customer’s browser. The frontend
    enables the customer to build a shopping cart and place an order.
    Upon payment, it triggers the respective business logic to satisfy
    the order. This component is not included with Taler, but rather
    assumed to exist at the merchant.
    The `Merchant API Tutorial <https://tutorials.taler.net/dev/merchant-api/>`_ gives an
    introduction for how to integrate Taler with Web shop frontends.
 -  A *back-office* application that enables the shop operators to view
    customer orders, match them to financial transfers, and possibly
    approve refunds if an order cannot be satisfied. This component is
    not included with Taler, but rather assumed to exist at the
    merchant. The :ref:`Merchant Backend API <merchant-api>` provides
    the API specification that should be reviewed to integrate such a
    back-office with the Taler backend.
 -  A Taler-specific payment *backend* which makes it easy for the frontend
    to process financial transactions with Taler. This manual primarily
    describes how to install and configure this backend.
 -  A *DBMS* which stores the transaction history for the Taler backend.
    For now, the GNU Taler reference implementation only supports
    PostgreSQL, but the code could be easily extended to support another
    DBMS.  Please review the PostgreSQL documentation for details on
    how to configure the database.
 
 The following image illustrates the various interactions of these key
 components:
 
 .. image:: images/arch-api.png
 
 .. index:: RESTful
 
 Basically, the backend provides the cryptographic protocol support, stores
 Taler-specific financial information in a DBMS and communicates with the GNU
 Taler exchange over the Internet. The frontend accesses the backend via a
 RESTful API. As a result, the frontend never has to directly communicate with
 the exchange, and also does not deal with sensitive data. In particular, the
 merchant’s signing keys and bank account information are encapsulated within
 the Taler merchant backend.
 
 A typical deployment will additionally include a full-blown Web server (like
 Apache or Nginx). Such a Web server would be responsible for TLS termination and
 access control to the ``/private/`` and ``/management/`` API endpoints of the
 merchant backend. Please carefully review the section on :ref:`secure setup
 <Secure-setup>` before deploying a Taler merchant backend into production.
 
 
 Terminology
 ===========
 
 This chapter describes some of the key concepts used throughout the manual.
 
 Instances
 ---------
 
 .. index:: instance
 
 The backend allows a single HTTP server to support multiple independent shops
 with distinct business entities sharing a single backend.  An *instance* is
 the name or identifier that allows the single HTTP server to determine which
 shop a request is intended for.  Each instance has its own base URL in the
 REST API of the merchant backend (``/instances/$INSTANCE/``).  Each instance
 can use its own bank accounts and keys for signing contracts. All major
 accounting functionality is separate per instance.  Access to each instance is
 controlled via a bearer token (to be set in the HTTP "Authorization" header).
 All instances share the same *database*, top-level HTTP(S) address and the
 main Taler configuration (especially the accepted *currency* and *exchanges*).
 
   .. note::
 
     This documentation does not use the term "user" or "username" in
     conjunction with instances as that might create confusion between
     instances with paying customers using the system.  We also do not use the
     term "account" in conjunction with instances, as that might cause
     confusion with bank accounts.  That said, conceptually it is of course
     acceptable to consider instances to be the "users" or "accounts" of a
     merchant backend and the bearer token is equivalent to a passphrase.
 
 .. _instance-bank-account:
 
 Instance Bank Accounts
 ----------------------
 
 .. index:: Bank account
 
 To receive payments, an instance must have configured one or more bank
 *accounts*.  When configuring the bank account of an instance, one should
 ideally also provide the address and credentials of an HTTP service
 implementing the :ref:`Taler Bank Revenue HTTP API
 <taler-bank-merchant-http-api>`.  Given such a service, the GNU Taler merchant
 backend can automatically reconcile wire transfers from the exchange to the
 merchant's bank account with the orders that are being settled.
 
 This documentation exclusively uses the term *account* for the bank
 accounts of a merchant or shop that may be associated with an instance.
 
 .. note::
 
    When an instance has **more than one** bank account configured, there is
    no notion of a "default" or "primary" account: *any* of the configured
    accounts may receive the funds for a given transaction, and which one is
    used is **not predictable from the merchant UI**.  The account is chosen
    per transaction based on what the settling exchange supports — i.e. the
    wire method and account restrictions of that exchange.  For example, if an
    instance offers both a CH-IBAN and a DE-IBAN account, one exchange may
    settle to the CH account while another settles to the DE account; adding an
    ``x-taler-bank`` account introduces yet another possibility.  If you need
    funds to arrive in a specific account, configure only that account.
 
 Inventory
 ---------
 
 .. index:: inventory
 .. index:: product
 .. index:: lock
 .. index:: unit
 .. index:: order
 
 The Taler backend offers inventory management as an optional function.
 Inventory is tracked per instance and consists of *products* sold in
 *units*. Inventory can be finite (physical stock) or infinite (for digital
 products).  Products may include previews (images) to be shown to the user as
 well as other meta-data. Inventory management allows the frontend to *lock*
 products, reserving a number of units from stock for a particular (unpaid)
 *order*. The backend can keep track of how many units of a product remain in
 stock and ensure that the number of units sold does not exceed the number of
 units in stock.
 
 Inventory management is optional, and it is possible for the frontend to
 include products in orders that are not in the inventory. The frontend
 can also override prices of products in the inventory or set a total price
 for an order that is different from the price of the sum of the products
 in the order.
 
 
 Orders and Contracts
 --------------------
 
 .. index:: order
 .. index:: terms
 .. index:: contract
 .. index:: claim
 .. index:: pay
 .. index:: refund
 .. index:: wire deadline
 .. index:: lock
 .. index:: legal expiration
 
 In Taler, users pay merchants for *orders*. An order is first created by the
 merchant. To create an order, the merchant must specify the specific *terms*
 of the order.  Order *terms* include details such as the total amount to be
 paid, payment fees the merchant is willing to cover, the set of products to
 deliver, a delivery location and many other details.  The :ref:`merchant API
 specification <contract-terms>` specifies the full set of possible order
 terms.
 
 After an order is created, it is *claimed* by a wallet. Once an order is
 claimed by a specific wallet, only that wallet will be able to pay for this
 order, to the exclusion of other wallets even if they see the same order URL.
 Sharing order URLs is explicitly allowed: if a user shares an order URL
 with another user, that other user should be given the opportunity to
 purchase the same product.
 
 To prevent unauthorized wallets from claiming an order, merchants can specify
 that claims require authorization in the form of a *claim token*. This is
 useful in case the order ID is predictable (say because an existing order ID
 scheme with predictable order IDs from the merchant frontend is used) and at
 the same time malicious actors claiming orders is problematic (say because of
 limited stocks). The use of claim tokens is optional, but if a claim token is
 used, it must be provided to the wallet as part of the order URI.
 
 Additionally, when stocks are limited, you can configure Taler to set a
 *product lock* on items (say, while composing the shopping cart).  These
 locks will ensure that the limited stock is respected when making offers
 to consumers.
 
 A wallet may *pay* for a claimed order, at which point the order turns into a
 (paid) *contract*.  Orders have a configurable expiration date (the
 ``pay_deadline``) after which the commercial offer expires and any stock of
 products *locked* by the order will be automatically released, allowing the
 stock to be sold in other orders.  When an unpaid order expires, the customer
 must request a fresh order if they still want to make a purchase.
 
 Once a contract has been paid, the merchant should fulfill the contract.  It
 is possible for the merchant to *refund* a contract order, for example if the
 contract cannot be fulfilled after all. Refunds are only possible after the
 customer paid and before the exchange has *wired* the payment to the
 merchant. Once the funds have been wired, refunds are no longer allowed by the
 Taler exchange.  The *wire deadline* specifies the latest point in time by
 which an exchange must wire the funds, while the (earlier) *refund deadline*
 specifies the earliest point in time when an exchange may wire the funds.
 Thus, refunds are always possible between the time of purchase and the
 refund deadline, but may remain possible until the wire deadline.
 
 Contract information is kept for legal reasons in the merchant database.  The
 main legal reason is typically to provide tax records in case of a tax audit.
 After the *legal expiration* (by default: a decade), contract information is
 deleted when running the garbage collector using ``taler-merchant-dbinit``.
 
 
 .. _template:
 
 Templates
 ---------
 
 .. index:: Template
 
 Usually, a merchant must use an authenticated endpoint to create an order and
 then share the link to the order with a wallet. Templates are a mechanism that
 allows wallets to create their own orders directly, using a public endpoint.
 The template fixes some properties of the contracts created from it, while
 other details may be left for the customer to provide.  Templates are useful
 in cases where the point-of-sale of a merchant is offline (and thus cannot
 setup an order), or even in cases where a simple static QR code is desired to
 accept payments or donations.
 
 When generating a template, the "summary" text of the contract and the
 "amount" to be paid by the customer can be fixed or left for the customer to
 specify.  If the customer is expected to provide either or both of these
 values, the template link (or QR code) can specify a default value. For
 example, a cafeteria with a fixed price lunch may use a "lunch" template with
 both values fixed to the lunch price and the "lunch" product, a bakery might
 fix the summary to "baked goods" but allow the customer to enter the amount
 based on the total price of the items being bought, and a charity may allow
 donating an arbitrary amount and summary message while also suggesting default
 values.
 
 If an offline merchant wants to confirm that a customer did actually pay the
 agreed amount using an order derived from a template, they can associate an
 OTP device with the template.
 
 
 .. _otp-device:
 
 OTP Devices
 -----------
 
 .. index:: OTP
 .. index:: TOTP
 
 A One-Time-Password (OTP) generator is a device or application that generates
 a 4 to 8 digit code typically used for authentication. The widely used TOTP
 standard is described in `RFC 6238 <https://www.rfc-editor.org/rfc/rfc6238>`_.
 For GNU Taler merchant backends, OTP devices are used as a way to assure a
 merchant without network connectivity that a customer made a digital
 payment. The idea is described in depth in our `SUERF Policy Brief
 <https://www.suerf.org/suer-policy-brief/69851/practical-offline-payments-using-one-time-passcodes>`_.
 To use this method, a merchant must configure the OTP device's shared secret
 in the merchant backend, and then associate the OTP device with a
 :ref:`template`.  Once the customer has paid, they are given a list of OTP
 codes which must be shown to the merchant who can check that at least one of
 the codes matches their OTP device, proving that the customer made the
 payment.
 
 
 Transfers
 ---------
 
 .. index:: transfer
 .. index:: wire transfer
 
 The Taler backend can be used to verify that the exchange correctly wired all
 of the funds to the merchant. However, if no :ref:`Taler Bank Revenue HTTP API
 <taler-bank-merchant-http-api>` was provided for the respective bank account,
 the backend does not have access to the incoming wire transfers of the
 merchant's bank account. In this case, merchants should manually provide the
 backend with wire *transfer* data that specifies the *wire transfer subject*
 and the amount that was received. Given this information, the backend can
 detect and report any irregularities that might arise.
 
 
 Webhooks
 --------
 
 .. index:: webhook
 
 A webhook is a pre-defined HTTP request that the GNU Taler merchant backend
 will make upon certain events, such as an order being paid or refunded. When
 the configured event happens, the merchant backend will make an HTTP request
 to the endpoint configured in the webhook configuration, possibly sending
 selected data about the event to the respective Web service. Webhooks can be
 used to trigger additional business logic outside of the GNU Taler merchant
 backend.
 
 
 Installation
 ============
 
 This chapter describes how to install the GNU Taler merchant backend.
 
 .. _Generic-instructions:
 
 Installing the GNU Taler binary packages on Debian
 --------------------------------------------------
 
 .. include:: frags/installing-debian.rst
 
 .. include:: frags/apt-install-taler-merchant.rst
 
 
 Installing the GNU Taler binary packages on Ubuntu
 --------------------------------------------------
 
 .. include:: frags/installing-ubuntu.rst
 
 .. include:: frags/apt-install-taler-merchant.rst
 
 
 Installing from source
 ----------------------
 
 The following instructions will show how to install a GNU Taler
 merchant backend from source.
 
 The package sources can be found in our
 `download directory <http://ftpmirror.gnu.org/taler/>`__.
 
 .. include:: frags/semver.rst
 
 First, the following packages need to be installed before we can compile the
 backend:
 
 .. include:: frags/list-of-dependencies.rst
 
 .. include:: frags/installing-gnunet.rst
 
 .. include:: frags/install-before-check.rst
 
 There is no need to actually run a GNUnet peer to use the Taler merchant
 backend -- all the merchant needs from GNUnet is a number of headers and
 libraries!
 
 .. include:: frags/installing-taler-exchange.rst
 
 There is no need to actually run a Taler exchange to use the Taler merchant
 backend -- all the merchant needs from the Taler exchange is a few headers and
 libraries!
 
 .. note::
 
   There is an additional **optional** dependency that you could install to
   obtain support for tax-deductible donations. This is only useful for
   charities and only in countries with tax authorities that operate a Donau to
   register charities and accept Taler-style digitally signed donation
   statements.  As of right now, we are pretty sure that list is right now
   empty. But, if you want to experiment with Taler-style donation statements,
   you need to install Donau after the exchange and before the merchant.
 
 .. include:: frags/install-before-check.rst
 
 .. include:: frags/installing-taler-merchant.rst
 
 .. include:: frags/install-before-check.rst
 
 
 
 How to configure the merchant backend
 =====================================
 
 .. index:: taler-merchant.conf
 
 The installation already provides reasonable defaults for most of the
 configuration options. However, some must be provided, in particular the
 database that the backend should use. By default, the file
 ``$HOME/.config/taler-merchant.conf`` is where the Web shop administrator specifies
 configuration values that augment or override the defaults.
 Note that when using our binary packages, the systemd service files
 force the use of ``/etc/taler-merchant/taler-merchant.conf`` as the main configuration file.
 
 
 .. include:: frags/configuration-format.rst
 
 
 .. _Backend-options:
 
 Backend options
 ---------------
 
 .. index:: DBMS
 .. index:: PostgreSQL
 .. index:: UNIX domain socket
 .. index:: TCP
 .. index:: port
 .. index:: currency
 .. index:: KUDOS
 .. index:: exchange
 .. index:: instance
 .. index:: wire format
 
 The following table describes the options that commonly need to be
 modified. Here, the notation ``[$SECTION]/$OPTION`` denotes the option
 ``$OPTION`` under the section ``[$SECTION]`` in the configuration file.
 
 
 Service address
 ^^^^^^^^^^^^^^^
 
 The service address specifies where the taler-merchant-httpd should listen for
 requests. When using the Debian/Ubuntu packages, these options will already be
 configured correctly for the included Nginx and Apache configurations and will
 not need any changes.
 
 The following option sets the transport protocol used by the merchant backend:
 
 .. code-block:: ini
 
       [MERCHANT]
       SERVE = unix # or tcp
 
 If this option is set to
 
 -  ``tcp`` then we need to set the TCP port in ``[MERCHANT]/PORT``;
 
 -  ``unix`` then we need to set the unix domain socket path and mode
    in ``[MERCHANT]/UNIXPATH`` and ``[MERCHANT]/UNIXPATH_MODE``. The
    latter takes the usual permission mask given as a number, e.g. 660
    for user/group read-write access.
 
 The frontend can then connect to the backend over HTTP using the specified
 address. If frontend and backend run within the same operating system, the
 use of a UNIX domain socket is recommended to avoid accidentally exposing
 the backend to the network.
 
 To run the Taler backend on TCP port 9966 (the default), use:
 
 .. code-block:: ini
 
    [MERCHANT]
    SERVE = tcp
    PORT = 9966
 
 .. note::
 
    If you need to change where the taler-merchant-httpd listens for requests,
    you should edit ``/etc/taler-merchant/merchant-overrides.conf``.  By default, the
    Taler merchant package will use a UNIX domain socket at
    ``/run/taler-merchant/merchant-httpd/merchant-http.sock``. For the best possible
    security it is recommended to leave this in place and configure a reverse
    proxy (Nginx or Apache) as described below.
 
    When using the Debian/Ubuntu packages, the use of a UNIX domain socket
    is already pre-configured in the ``/etc/taler-merchant/conf.d/merchant.conf``
    configuration file.  Suitable reverse proxy configuration
    file templates (``taler-merchant``) are be installed in the
    respective ``sites-available`` directories of Apache and Nginx.
 
 
 
 Currency
 ^^^^^^^^
 
 Which currency the SPA uses by default is
 specified using the option:
 
 .. code-block:: ini
 
       [MERCHANT]
       CURRENCY = EUR # or USD, ...
 
 When testing with the Taler demonstration exchange at
 https://exchange.demo.taler.net/ you probably want to set this
 value to ``KUDOS``:
 
 .. code-block:: ini
 
        [MERCHANT]
        CURRENCY = KUDOS
 
 The merchant backend is already multi-currency capable, and will allow you to
 create orders in all currencies for which an exchange is configured, not just
 the default currency.  However, the Web interface does not yet offer
 multi-currency support and often only supports using the default currency.
 
 .. note::
 
    When using the Debian/Ubuntu packages, these options should be
    configured in the ``/etc/taler-merchant/taler-merchant.conf`` configuration file
    (alternatively, you can also edit ``/etc/taler-merchant/merchant-overrides.conf``).
    However, you must edit the ``taler-merchant.conf`` file manually and **must not**
    use ``taler-merchant-config`` to do this, as that would inline the include
    directives and destroy the carefully setup path structure.
 
 
 Database
 ^^^^^^^^
 
 In principle it is possible for the backend to support different DBMSs.
 The option
 
 .. code-block:: ini
 
       [MERCHANT]
       DB = postgres
 
 specifies which DBMS is to be used. However, currently only the value
 ``postgres`` is supported. This is also the default.
 
 In addition to selecting the DBMS software, the backend requires
 DBMS-specific options to access the database.
 
 .. note::
 
    The **taler-merchant-dbconfig** tool can be used to automate the database
    setup. When using the Debian/Ubuntu packages, the user should already have
    been created, so you can just run the tool without any arguments and should
    have a working database configuration.
 
    The tool preserves an existing database unless explicitly invoked with
    ``-r``. Existing databases must have the expected ownership and migration
    privileges. It provisions only the default local PostgreSQL cluster; for
    remote databases, provision the database separately and use
    ``taler-merchant-dbinit`` with the appropriate database identity.
 
 
 For the ``postgres`` backend, you need to specify:
 
 .. code-block:: ini
 
       [merchantdb-postgres]
       CONFIG = "postgres:///taler-merchant"
 
 This option specifies a PostgreSQL access path, typically using the format
 ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the PostgreSQL
 database you want to use (here, ``taler-merchant`` on the local machine).
 Suppose ``$USER`` is the name of the user who will run the backend process
 (usually ``taler-merchant-httpd``). Then, you need to first run:
 
 .. code-block:: console
 
    $ sudo -u postgres createuser -d $USER
 
 as the PostgreSQL database administrator (usually ``postgres``) to
 grant ``$USER`` the ability to create new databases. Next, you should
 as ``$USER`` run:
 
 .. code-block:: console
 
    $ createdb $DBNAME
 
 to create the backend’s database. Here, ``$DBNAME`` must match the
 database name given in the configuration file.
 
 Now you should be able to create the tables and indices. To do this, run as
 ``$USER`` (usually ``taler-merchant-httpd``):
 
 .. code-block:: console
 
    $ taler-merchant-dbinit
 
 You may improve your security posture if you now REVOKE the rights to CREATE,
 DROP or ALTER tables from ``$USER``. However, if you do so, please be aware
 that you may have to temporarily GRANT those rights again when you update the
 merchant backend.  For details on how to REVOKE or GRANT these rights, consult
 the PostgreSQL documentation.
 
 .. include:: frags/db-stores-sensitive-data.rst
 
 
 .. index: MASTER_KEY
 
 Exchange
 ^^^^^^^^
 
 To add an exchange to the list of trusted payment service providers, you
 create a section with a name that starts with “MERCHANT-EXCHANGE-”. In that
 section, the following options need to be configured:
 
 -  The ``EXCHANGE_BASE_URL`` option specifies the exchange’s base URL.
    For example, to use the Taler demonstrator, specify:
 
    .. code-block:: ini
 
       [merchant-exchange-kudos]
       EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/"
 
 -  The KUDOS demo exchange and others are usually enabled by default
    in the distribution so you can easily test your backend. If you want
    to disable KUDOS, for example because you only want to support
    CHF or EUR, do not delete the "kudos.conf", but instead disable
    it explicitly in your main taler-merchant.conf configuration
    file using:
 
    .. code-block:: ini
 
       [merchant-exchange-kudos]
       DISABLED = YES
 
    This is also the preferred way to disable any other exchange that
    may be enabled by default. You can get a list of all of these
    exchange configuration sections using
    ``taler-merchant-config -S | grep merchant-exchange-``.
 
 -  The ``MASTER_KEY`` option specifies the exchange’s master public key
    in base32 encoding. For the Taler demonstrator, use:
 
    .. code-block:: ini
 
       [merchant-exchange-kudos]
       MASTER_KEY = "GNRJCH0HYKN59939JC0CJ2JDC7ZNEBSATJFF00CVS3WPG4TQEA7G"
 
   You can find out this key by running ``curl https://exchange.demo.taler.net/keys | jq .master_public_key``.
 
 -  The ``CURRENCY`` option specifies the exchange’s currency.
    For the Taler demonstrator, use:
 
    .. code-block:: ini
 
       [merchant-exchange-kudos]
       CURRENCY = "KUDOS"
 
 
 Note that multiple exchanges can be added to the system by using different
 identifiers in place of ``KUDOS`` in the example above. One exchange will only
 ever support a single currency; thus, if you need support for multiple
 currencies, you must add multiple exchanges.
 
 The merchant already ships with a default configuration that contains the
 ``merchant-exchange-kudos`` section from above.
 
 .. note::
 
    Manually setting up exchanges is only recommended under special
    circumstances. In general, GNU Taler distributions will include trustworthy
    exchanges (for each currency) in the default configuration, and there is
    rarely a good reason for trusting an exchange that has no relationship
    with the GNU Taler development team.
 
 
 .. _Sample-backend-configuration:
 
 Sample backend configuration
 ----------------------------
 
 .. index:: configuration
 
 The following is an example for a complete backend configuration:
 
 .. code-block:: ini
 
    [merchant]
    # Default currency; note that multi-currency support is still
    # a bit experimental...
    CURRENCY = KUDOS
    SERVE = TCP
    PORT = 9966
    DATABASE = postgres
 
    [merchantdb-postgres]
    CONFIG = postgres:///taler-merchant
 
    [merchant-exchange-kudos]
    EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
    MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
    CURRENCY = KUDOS
 
 Given the above configuration, the backend will use a PostgreSQL database
 named ``donations`` running on the same host.
 
 The backend will deposit the coins it receives to the exchange at
 https://exchange.demo.taler.net/, which has the master key
 ``FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0``.
 
 
 .. _Launching-the-backend:
 
 Launching the backend
 ---------------------
 
 .. index:: backend
 .. index:: taler-merchant-httpd
 
 Assuming you have configured everything correctly, you can launch the
 merchant backend as ``$USER`` using (to provide a trivial example):
 
 .. code-block:: console
 
    $ taler-merchant-httpd &
    $ taler-merchant-webhook &
    $ taler-merchant-kyccheck &
    $ taler-merchant-wirewatch &
    $ taler-merchant-depositcheck &
    $ taler-merchant-exchangekeyupdate &
    $ taler-merchant-reconciliation &
 
 .. note::
 
   If you compiled the merchant backend with support for donation
   statements via Donau, you need to additionally launch
   ``taler-merchant-donaukeyupdate``.
 
 To ensure these processes run always in the background and also after
 rebooting, you should use systemd, cron or some other init system of your
 operating system to launch the process.  You should also periodically re-start
 these services to prevent them from exhausting the memory utilization of the
 PostgreSQL database.  Consult the documentation of your operating system for
 how to start and stop daemons.
 
 .. note::
 
    When using the Debian/Ubuntu packages, the systemd configuration
    will already exist. You only need to enable and start the service
    using ``systemctl enable taler-merchant.target`` and
    ``systemctl start taler-merchant.target``. Additionally, you should
    review the ``/etc/apache2/sites-available/taler-merchant.conf``
    or ``/etc/nginx/sites-available/taler-merchant`` (these files
    contain additional instructions to follow), symlink it to
    ``sites-enabled/`` and restart your HTTP server. After that, you
    should be able to visit the merchant backend at the respective
    HTTP(S) endpoint.
 
 If everything worked as expected, the command
 
 .. code-block:: console
 
    $ wget -O - http://localhost:9966/config
 
 should return some basic configuration status data about the service.
 
 Please note that your backend might then be globally reachable without
 any access control.  You can either:
 
   * Use the ``--auth=$TOKEN`` command-line option to **taler-merchant-httpd** to set an access token to be provided in an ``Authorization: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified.
   * Set the ``TALER_MERCHANT_TOKEN`` environment variable to ``$TOKEN`` for the same effect. This method has the advantage of ``$TOKEN`` not being visible as a command-line interface to other local users on the same machine.
   * Set up an instance with an authentication token before some unauthorized person has a chance to access the backend.  As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token!
 
 Production systems should additionally be configured to bind to a UNIX domain socket
 and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`.
 
 
 Multi-factor authentication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The merchant backend supports multi-factor authentication for critical
 endpoints, including issuing access token, changing login credentials,
 modifying the bank account and deleting the instance. To use
 multi-factor authentication, the merchant backend must be configured
 with helper programs that can be used to send e-mails or SMS messages.
 
 
 .. code-block:: ini
 
       [MERCHANT]
       HELPER_SMS = sms_helper.sh
       HELPER_EMAIL = email_helper.sh
 
 These scripts will be called by the merchant backend with the
 first argument being the phone number or the e-mail address, and
 with the message with the TAN code to send to the user on standard
 input. The shell scripts must exit with a status code of 0 on
 success.  A trivial e-mail helper would look like this:
 
 .. code-block:: sh
 
       #!/bin/sh
       exec mail --subject="TAN code for the Taler merchant backend" "$1"
 
 Here, ``mail`` refers to the classic UNIX mail command.
 Example scripts can also be found in the `GNU Anastasis Git
 <https://git.taler.net/anastasis.git/tree/src/authorization>`_.
 
 
 Self-provisioning
 ^^^^^^^^^^^^^^^^^
 
 Self-provisioning allows anyone to create a merchant instance. This
 is useful if a merchant backend is offered as a public service. In this
 case, you should set:
 
 .. code-block:: ini
 
       [MERCHANT]
       ENABLE_SELF_PROVISIONING = YES
 
 
 To enable self-provisioned users to reset their passwords if they
 forgot them, the merchant backend requires two other authentication
 methods to be available and validated when the instance is
 self-provisioned.  This can be enabled using:
 
 .. code-block:: ini
 
       [MERCHANT]
       MANDATORY_TAN_CHANNELS = sms email
 
 With this setting, users that self-provision an instance must first
 demonstrate control over the e-mail address and phone number provided,
 and can thus later reset their password without needing support from
 the administrator.
 
 To also require one of these channels as a second factor when a merchant
 changes its password, set:
 
 .. code-block:: ini
 
       [MERCHANT]
       PASSWORD_CHANGE_MFA = YES
 
 The current password is still required.  When both SMS and e-mail are usable,
 the merchant may complete either challenge.
 
 
 .. index:: instance
 .. _Instance-setup:
 
 
 Instance setup
 ==============
 
 We recommend the use of the single-page administration application (SPA) that
 is served by default at the base URL of the merchant backend.  You can use it
 to perform all steps described in this section (and more!), using a simple Web
 interface. Alternatively, you can also use the ``wget`` commands given below.
 
 Regardless of which approach you use, the first step for using the backend
 involves the creation of the ``admin`` instance. The ``admin`` instance can
 also create, configure or delete other instances, similar to the ``root``
 account on UNIX.  When no instance exists, then the backend is reachable
 without any access control (unless you configured some in the reverse proxy).
 
 .. note::
 
   If you created a non-admin instance first, you cannot create an ``admin``
   instance via the SPA anymore. In this case, you can only create an
   administrative account by using the command-line. By invoking
   ``taler-merchant-passwd --instance=admin $PASSWORD`` you can set both the
   password and create an ``admin`` instance if it does not yet exist.
   However, for non-admin instances, you can only set the password with this tool.
 
 The following documentation shows how to handle any instance. Thus, if you
 want to have multiple instances, you may need to perform the steps multiple
 times, once for each instance.
 
 .. note::
 
   A potential security concern is that normal API usage leaks instance existence.
   This means unauthorized users can distinguish between the case where the
   instance does not exist (HTTP 404) and the case where access is denied
   (HTTP 403).
   This concern can be addressed using a properly configured
   :ref:`reverse proxy <reverse-proxy-configuration>`.
 
 
 Instance setup with the SPA
 ---------------------------
 
 In order to setup an instance, you need the merchant backend to already be
 running, and you must either have the credentials for the ``admin`` instance,
 or no instance must be configured at all yet.
 
 To start, point your browser to ``$PROTO://backend.$DOMAIN_NAME/``, replacing
 "$PROTO" with "https" or (rarely) "http" and "$DOMAIN_NAME" with your
 organization's DNS domain or subdomain.
 
 .. note::
 
    The label "backend" here is also just a suggestion, your administrator
    can in principle choose any name.
 
 You should be welcomed by the following merchant backoffice page:
 
 .. image:: screenshots/merchant_first_login.png
 
 After supplying the required fields, primarily the name of your organization
 and the desired access token, click ``confirm``.  You can change the instance
 settings later via the ``Settings`` entry in the menu on the left.
 
 
 Instance settings
 -----------------
 
 The settings dialog allows you to select an image to be used as a logo
 for your shop. Wallets may use that logo when showing contracts to
 highlight to customers which shop they are buying from.
 
 The settings dialog allows you to specify the address of your business
 and the jurisdiction the shop is under. Both will be embedded into the
 contracts and may be shown by the Taler wallet to customers that want
 to know these details.
 
 You must also configure whether you intend to pay transaction fees,
 or whether the customer is required to pay for any payment fees. If
 you do not cover the fees, the fees will be shown separately to the
 customer and added to the total of each order, which may discourage
 consumers from using the Taler payment method.  The specific
 magnitude of the fees cannot be configured here, as it depends on
 the amount of the order and is dynamically computed. Regardless of
 what you specify here, the front-end can override the acceptable
 fee amount for each order it creates.
 
 .. note::
 
   Details on the acceptable fee calculation
   are described in the Taler design document 47.
 
 Finally, you need to specify several settings relating to default
 deadlines.
 
   (1) The "Default payment delay" specifies when an offer expires.  The
   customer basically has this amount of time to pay, or the backend will
   refuse the payment and require the customer to get a new quote.
 
   (2) The "Default refund delay" specifies how long the customer may receive
   refunds. The refund period is cumulative on top of the "Default payment
   delay". Thus, the refund period ends independently of when the customer
   actually paid for the order. The exchange will **not** wire the funds to the
   merchant before the refund deadline lapses, as after the funds have been
   wired refunds using Taler are no longer possible.
 
   (3) The "Default wire transfer delay" specifies how soon the exchange
   **must** wire the funds **after** the refund deadline.  The delay is again
   cumulative on top of the "Default payment delay" and the "Default refund
   delay".  However, the resulting time is still not the actual wire
   deadline, as first the "Default wire rounding interval" is also considered.
 
   (4) The "Default wire rounding interval" specifies to what period the
   wire deadline should be rounded up to. The ultimate wire deadline is
   computed by adding the default payment, rounding and wire delays to
   the current time and rounding the resulting timestamp to the
   "Default wire rounding interval". Typical values include
   end-of-day, end-of-week, end-of-month, end-of-quarter or end-of-year.
 
 .. note::
 
   The wire deadline is rounded using the local timezone of the Taler merchant
   backend server, so if you want end-of-day payments make sure to run your
   merchant backend in your own timezone.
 
 Specifying larger values for the wire transfer delay and the wire rounding
 interval allows the exchange to aggregate more payments into larger wire
 transfers. The exchange is required by the protocol to initiate the wire
 transfer **before** the wire transfer deadline.
 
 All of the computed deadlines (payment, refund and wire transfer)
 are just defaults and can be modified by frontends for any
 specific order.
 
 
 Instance setup without the Web interface
 ----------------------------------------
 
 Instances can be created by POSTing a request to ``/management/instances``
 without using the Web interface.  This could be useful if you want to create
 many instances programmatically.  To create an instance without the Web
 interface create a file ``instance.json`` with an
 `InstanceConfigurationRequest`:
 
 .. code-block:: json
 
    {
      "id" : "admin",
      "name": "Example Inc.",
      "address": { "country" : "zz" },
      "auth": { "method" : "external"} ,
      "jurisdiction": { "country" : "zz" },
      "use_stefan": true,
      "default_pay_delay": { "d_ms" : 1209600000 }
      "default_refund_delay": { "d_ms" : 1209600000 }
      "default_wire_transfer_delay": { "d_ms" : 1209600000 },
    }
 
 The ``name`` field will be shown as the name of your shop. The ``address``
 field is expected to contain your shop's physical address. The various
 ``default_*`` values specify defaults for transaction fees your shop is
 willing to cover, how long offers made to the customer are valid, and how long
 the exchange has before it must wire the funds to your bank account. Those
 defaults can be modified for individual orders.  For details, see the
 :ref:`contract terms <contract-terms>` specification.
 
 You can then create the instance using:
 
 .. code-block:: console
 
    $ wget --post-file=instance.json http://localhost:9966/management/instances
 
 The base URL for the instance will then be ``http://localhost:9966/``.  You
 can create additional instances, which will then be reachable under
 ``http://localhost:9966/instances/$ID`` where ``$ID`` needs to be changed to
 the identifier value of the respective instance.
 
 Endpoints to modify (reconfigure), permanently disable (while keeping the data)
 or purge (deleting all associated data) instances exist as well and are documented
 in the :ref:`Merchant Backend API documentation <merchant-api>`.
 
 .. _instance-account-setup:
 
 Instance bank account setup
 ===========================
 
 Before you can use an instance productively, you need to configure one or more
 bank accounts. These bank accounts will be provided to the Taler exchange
 operator to tell it where to wire the income from your sales. Every bank
 account has an associated *wire method* which determines how an exchange can
 transfer the funds.  The most commonly supported wire method is *iban*, which
 implies that bank accounts are identified by IBAN numbers and wire transfers
 are to be executed between IBAN accounts.  For regional currency setups, the
 wire method could also be *x-taler-bank*.
 
 .. note::
 
    When using a regional currency, you need to first create a bank account at
    the regional bank. You may need to contact the respective administrator who
    can set one up.  After being able to login to the new bank account, you can
    see your bank account number by clicking on the ``Welcome, $USERNAME``
    message in the profile page.  Next to the bank account number, you can find
    a convenient button to copy the number to the clipboard.
 
 Not every exchange will support every *wire method*, and if you do not add a
 bank account with a wire method that is supported by a particular exchange,
 then you will not be able to receive payments via that exchange even if you
 configured the merchant backend to trust that exchange.
 
 The simplest way to configure an account is to use the Web interface which has
 specific forms for different wire methods.  First, select ``Bank account`` at
 the left of the page.  The following page should be shown:
 
 .. image:: screenshots/no_default_account_yet.png
 
 Click on the blue "+" sign on the top right of the page to add a new
 bank account. The following page should appear:
 
 .. image:: screenshots/enter_instance_details.png
 
 First, you should select the wire method, after which the dialog will show you
 additional fields specific to the wire method. For example, if you choose
 ``iban`` as the account type, the following page should appear:
 
 .. image:: screenshots/instance_iban_config.png
 
 Specifying the revenue gateway with username and password is optional and
 discussed in section :ref:`automatic-settlement-data-import` below.
 
 After providing the details and confirming, the shop is ready to generate orders
 and accept payments.
 
 
 
 Detecting Settlement: Manually Adding Transfers
 -----------------------------------------------
 
 The exchange may aggregate many small amounts into one larger wire transfer.
 If you want to safely determine which orders have been settled (final
 payment from the exchange has been received), the backend must learn about the
 wire transfers made into your bank account. Basically, as a secure system, we
 do not simply trust a claim by the exchange that it would transfer the money,
 but we allow each merchant to check settlements.
 
 An easy (but somewhat tedious) way to check settlements is to manually add
 every wire transfer that a merchant bank account has received from the
 exchange with the total amount and the wire transfer subject. Given this
 information, the merchant backend will inquire with the exchange which
 individual payments were aggregated, check that the total amount is correct,
 and will then flag the respective contracts as wired.
 
 You can manually enter wire transfers under ``Transfers``. However, this is
 tedious, and so if your banking setup supports it, we highly recommend
 using the automatic settlement data import.
 
 .. _automatic-settlement-data-import:
 
 Automatic Settlement Data Import
 --------------------------------
 
 To automatically import settlement data, you need to provide the merchant
 backend with the address and access credentials of a
 :ref:`taler-bank-merchant-http-api` for each bank account of an instance.  The
 revenue API endpoint will allow the merchant backend to obtain a list of all
 incoming wire transfers into your bank account and automatically import them
 into the list of confirmed wire transfers.
 
 Note that setting up a revenue API endpoint will usually require you to first
 ask your bank for EBICS access and to set up :ref:`libeufin-nexus` to provide
 the revenue API endpoint. The :ref:`libeufin-bank` used by regional currency
 setups also provides a revenue API endpoint at
 ``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``.  Thus, when using a
 regional currency setup, simply use the ``$BANK_URL`` of your bank and specify
 your bank login name and password in the :ref:`instance-account-setup` dialog.
 
 
 Manually creating an order using the SPA
 ========================================
 
 Arbitrary orders can also be created manually using the Web interface of
 the GNU Taler merchant backend. For this, log into the single page app (SPA)
 of the merchant backend using the authorization token of the respective
 instance you want to use.
 
 Click on ``Orders`` at the top left corner of the merchant backoffice page; the
 following page should appear
 
 .. image:: screenshots/create_orders.png
 
 You can then set up orders by providing all of the required fields of an
 order, in particular an order summary and a price. You can also set various
 optional fields or override instance default settings.
 
 After this the interface should show the following page with the related links
 to check the status of the order and let wallet pay for it.
 
 .. image:: screenshots/payment_links.png
 
 The order status page also shows you the progress of the order, including when
 a wallet has made the payment. You can also use the backend to approve refunds.
 
 In order to test the setup, it should be now possible to use the command line wallet
 to withdraw Taler coins and spend them to pay for the order we just created.
 
 In practice, you will rarely if ever setup orders manually like this. Instead,
 a `GNU Taler e-commerce front-end
 <https://taler.net/en/docs.html#extensions>`_ or the
 :ref:`taler-merchant-pos-app` will do this on-demand. Here, you will only need
 to provide the respective front-ends with the URL of your instance
 (e.g. ``https://backend.$DOMAIN/instances/$NAME``) and your access token.
 
 
 Paying an order
 ===============
 
 The payer simply scans the (dynamic) QR code to initiate the payment.  If a
 website is interacting with a WebExtension wallet, it may also directly
 trigger the GNU Taler wallet without requiring the user to explicitly scan the
 QR code.  The payer should now review the contract terms and applicable fees.
 Selecting "pay" will complete the transaction.  Typically, the wallet will
 then redirect the user to the fulfillment page where they can track the order
 or directly view the digital product that they purchased.
 
 
 Setting up a template
 =====================
 
 A template provides all or part of the information needed to setup an order
 and allows GNU Taler wallets to create an order.  Usually, the creation of
 orders is a privileged process that requires knowledge of the authorization
 code for the respective instance. With templates, a customer's wallet can
 directly create an order on-demand.  The information of a template can be
 partial, in which case the customer is expected to provide the remaining
 details, typically the summary and/or amount of the order.
 
 When setting up a template you need to specify all of the fixed inputs that
 the customer cannot change.  You can then generate a template QR code where
 you may additionally specify editable defaults for the order, such as a
 default summary or a default amount which may still be changed by the wallet.
 The resulting template QR code encodes the specific merchant backend, instance
 and template ID as well as the (editable) default values.  The resulting
 static QR code can then be printed and put on display.
 
 Customers can scan the QR code with their GNU Taler wallet, complete the
 missing details or edit the defaults (if any), and pay the resulting order.
 
 To secure template-based payments, you may specify a TOTP secret as part of
 the template. In this case, the merchant backend will send a set of TOTP
 payment confirmation codes to the GNU Taler wallet upon receiving a payment
 for an order created based on the template.  If the point-of-sale has a TOTP
 generator with the same secret, they can compare their TOTP code with the
 codes shown by the customer on their wallet. This provides additional
 assurance that the customer actually made the payment instead of just showing
 a fake confirmation screen.
 
 
 Paying with static QR codes
 ===========================
 
 The payer simply scans the (static) QR code to initiate the payment.  If the
 template does not specify a fixed amount, the payer will be prompted to enter
 the amount to be paid (and possibly given the opportunity to specify or alter
 the summary).  Selecting "pay" will complete the transaction.  If payment
 confirmations are configured by the merchant backend, the wallet will then
 display a TOTP confirmation code that can be shown to the merchant as a proof
 of payment.
 
 
 
 Setting up a webhook
 ====================
 
 To receive notifications when a purchase has been made or a refund was given
 to a wallet, you can set up webhooks in the GNU Taler merchant backend.
 Webhooks allow you to trigger HTTP(S) requests based on certain events.  A
 webhook is thus simply an HTTP request that the GNU Taler merchant backend
 will make when a certain event (such as a payment) happens.
 
 There are various providers that can send an SMS to a phone number based on an
 HTTP request.  Thus, by configuring such a provider in a webhook you can
 receive an SMS notification whenever a customer makes a payment.
 
 Webhooks are configured per instance.  In the Webhook configuration,
 you can specify which URL, which HTTP headers, which HTTP method and what HTTP
 body to send to the Webhook.  Webhooks are automatically retried (with
 increasing delays) when the target server returns a temporary error.
 
 `Mustach templates <https://mustache.github.io/mustache.5.html>`__ and a limited
 version of it is used when defining the contents of Webhooks.
 Depending on the triggering event, the templates will be expanded with event-specific
 data. Limited in this case means that only a specific string is being replaced
 with the event-specific data, no support for parsing conditions or nested structures
 is provided.
 
 
 Order created events
 --------------------
 
 For "order_created" events, the backend will provide the following
 information to the Mustache templating engine:
 
 * webhook_type: "order_created".
 * order_id: the identifier of the newly created order.
 * contract: the full JSON contract for the order (see :ref:`contract_terms <contract-terms>` for the structure).
 * instance_id: the merchant instance identifier that created the order.
 
 
 Order pay events
 ----------------
 
 For "pay" events, the backend will provide the following
 information to the Mustache templating engine:
 
 * webhook_type: "pay".
 * :ref:`contract_terms <contract-terms>`: the contract terms of the paid order.
 * order_id: the ID of the order that received the refund.
 
 
 Order refund events
 -------------------
 
 For "refund" events which are triggered when a refund is
 approved, the backend will provide the following information to the
 Mustache templating engine:
 
 * webhook_type: "refund".
 * timestamp: time of the refund (using a `Timestamp` with the time in seconds since the UNIX epoch).
 * order_id: the ID of the order that received the refund.
 * :ref:`contract_terms <contract-terms>`: the full JSON of the contract terms of the refunded order.
 * refund_amount: the amount that was being refunded.
 * reason: the reason entered by the merchant staff for granting the refund;
   be careful, you probably want to inform your staff if a webhook may expose
   this information to the consumer.
 
 
 Order settled events
 --------------------
 
 For "order_settled" events which are triggered when the
 **taler-merchant-reconciliation** service is able to map
 an incoming wire transfer from the exchange to a paid
 order, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "order_settled".
 * order_id: The unique identifier of the order that has been fully settled (all payments completed and wired to the merchant).
 * wtid: The wire transfer ID of the settlement.
 
 Category added events
 ---------------------
 
 For "category_added" events, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "category_added".
 * category_serial: The unique identifier of the newly added category.
 * category_name: The name of the newly added category.
 * merchant_serial: The unique identifier of the merchant associated with the category.
 
 
 Category updated events
 -----------------------
 
 For "category_updated" events, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "category_updated".
 * category_serial: The unique identifier of the updated category.
 * old_category_name: The name of the category before the update.
 * category_name: The name of the category after the update.
 * category_name_i18n: The internationalized name of the category after the update.
 * old_category_name_i18n: The internationalized name of the category before the update.
 
 
 Category deleted events
 -----------------------
 
 For "category_deleted" events, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "category_deleted".
 * category_serial: The unique identifier of the deleted category.
 * category_name: The name of the deleted category.
 
 
 Inventory added events
 ----------------------
 
 For "inventory_added" events, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "inventory_added".
 * product_serial: The unique identifier of the newly added product.
 * product_id: The ID of the newly added product.
 * description: The description of the newly added product.
 * description_i18n: The internationalized description of the newly added product.
 * unit: The unit of the newly added product.
 * image: The image of the newly added product.
 * taxes: The taxes of the newly added product.
 * price: The price of the newly added product.
 * total_stock: The total stock of the newly added product.
 * total_sold: The total sold of the newly added product.
 * total_lost: The total lost of the newly added product.
 * address: The address of the newly added product.
 * next_restock: The next restock of the newly added product.
 * minimum_age: The minimum age for buying the newly added product.
 
 Inventory updated events
 ------------------------
 
 For "inventory_updated" events, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "inventory_updated".
 * product_serial: The unique identifier of the updated product.
 * product_id: The ID of the product.
 * old_description: The description of the product before the update.
 * description: The description of the product after the update.
 * old_description_i18n: The internationalized description of the product before the update.
 * description_i18n: The internationalized description of the product after the update.
 * old_unit: The unit of the product before the update.
 * unit: The unit of the product after the update.
 * old_image: The image of the product before the update.
 * image: The image of the product after the update.
 * old_taxes: The taxes of the product before the update.
 * taxes: The taxes of the product after the update.
 * old_price: The price of the product before the update.
 * price: The price of the product after the update.
 * old_total_stock: The total stock of the product before the update.
 * total_stock: The total stock of the product after the update.
 * old_total_sold: The total sold of the product before the update.
 * total_sold: The total sold of the product after the update.
 * old_total_lost: The total lost of the product before the update.
 * total_lost: The total lost of the product after the update.
 * old_address: The address of the product before the update.
 * address: The address of the product after the update.
 * old_next_restock: The next restock of the product before the update.
 * next_restock: The next restock of the product after the update.
 * old_minimum_age: The minimum age for buying the product before the update.
 * minimum_age: The minimum age for buying the product after the update.
 
 
 Inventory deleted events
 ------------------------
 
 For "inventory_deleted" events, the backend will provide the following information to the limited
 Mustache templating engine:
 
 * webhook_type: "inventory_deleted".
 * product_serial: The unique identifier of the deleted product.
 * product_id: The ID of the deleted product.
 * description: The description of the deleted product.
 * description_i18n: The internationalized description of the deleted product.
 * unit: The unit of the deleted product.
 * image: The image of the deleted product.
 * taxes: The taxes of the deleted product.
 * price: The price of the deleted product.
 * total_stock: The total stock of the deleted product.
 * total_sold: The total sold of the deleted product.
 * total_lost: The total lost of the deleted product.
 * address: The address of the deleted product.
 * next_restock: The next restock of the deleted product.
 * minimum_age: The minimum age for buying the deleted product.
 
 
 .. _Secure-setup:
 
 Secure setup
 ============
 
 .. index:: security
 .. index:: TLS
 
 The Taler backend is deliberately simple in terms of support for access
 control or transport layer security (TLS).  Thus, production setups **must**
 deploy the Taler backend behind an HTTP(S) server that acts as a *reverse
 proxy*, performs TLS termination and authentication and then forwards requests
 to the backend.
 
 
 Using UNIX domain sockets
 -------------------------
 
 To ensure that the merchant backend is not exposed directly to the network,
 you *should* bind the backend to a UNIX domain socket:
 
 .. code-block:: ini
 
    [MERCHANT]
    SERVE = unix
    UNIXPATH = "/some/path/here.sock"
 
 Do not use a UNIX domain socket path in "/tmp": systemd (or other init
 systems) may give Web servers a private "/tmp" thereby hiding UNIX domain
 sockets created by other users/processes in "/tmp".
 
 If UNIX domain sockets are for some reason not possible, you *may* use a
 host-based firewall to block access to the TCP port of the merchant backend,
 but this is *not recommended*.  If you do need a TCP socket, you should
 instead strongly consider using the "BIND_TO" option to at least bind it only
 to "localhost".
 
 .. _reverse-proxy-configuration:
 
 Reverse proxy configuration
 ---------------------------
 
 Nginx
 ^^^^^
 
 For Nginx, a possible basic reverse proxy configuration would be:
 
 .. code-block:: nginx
 
       proxy_pass http://unix:/some/path/here.sock;
       proxy_redirect off;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-Host "example.com";
       proxy_set_header X-Forwarded-Proto "https";
 
 Note that the above assumes your domain name is ``example.com`` and that you
 have TLS configured.  Leave out the last line if your Nginx reverse proxy does
 not have HTTPS enabled.  Make sure to restart the ``taler-merchant-httpd``
 process after changing the ``SERVE`` configuration.
 
 Apache
 ^^^^^^
 
 In Apache, make sure you have ``mod_proxy``, ``mod_proxy_http`` and
 ``mod_headers`` enabled:
 
 .. code-block:: console
 
    $ a2enmod proxy
    $ a2enmod proxy_http
    $ a2enmod headers
 
 Then configure your Apache reverse proxy like this (you may change the
 endpoint):
 
 .. code-block:: apacheconf
 
        <Location "/">
        ProxyPass "unix:/some/path/here.sock|http://example.com/"
        RequestHeader add "X-Forwarded-Proto" "https"
        </Location>
 
 Note that the above again assumes your domain name is ``example.com`` and that
 you have TLS configured.  Note that you must add the ``https`` header unless
 your site is not available via TLS.
 
 .. _auto-reverse-proxy-configuration:
 
 Automated Reverse Proxy Configuration
 -------------------------------------
 
 GNU Taler provides a helper script, ``taler-merchant-rproxy-setup``, that
 automates the most common reverse-proxy configuration tasks for both Nginx
 and Apache:
 
 -   Detects (or lets you choose) Nginx vs. Apache
 -   Verifies and enables required modules and packages
 -   Obtains (or skips) TLS certificates via Certbot (unless ``--httponly``)
 -   Backs up and populates the stock configuration with your domain
 -   Optionally forces HTTP → HTTPS redirection (``--httpsonly``)
 -   Enables the site and reloads the web server
 
 Usage
 ^^^^^
 
 .. code-block:: console
 
    taler-merchant-rproxy-setup \
      --domain <example.com> [--nginx | --apache] [--httponly | --httpsonly]
 
 Options
 ^^^^^^^
 
 ``--domain <name>``
     (Required) The public domain name to configure.
 
 ``--nginx``
     Force use of Nginx (overriding auto-detection).
 
 ``--apache``
     Force use of Apache2 (overriding auto-detection).
 
 ``--httponly``
     Only configure HTTP (no TLS). Skips Certbot entirely.
 
 ``--httpsonly``
     Enable HTTPS and add an HTTP→HTTPS redirect.
 
 ``-h, --help``
     Show this help message and exit.
 
 .. note::
 
    This script must be run as root (for example via ``sudo``) and requires
    that either Nginx or Apache2 (and Certbot for non-HTTP-only modes) be
    installed on the system.
 
 
 Access control
 --------------
 
 All endpoints with ``/private/`` in the URL must be restricted to authorized
 users of the respective instance.  Specifically, the HTTP server must be
 configured to only allow access to ``$BASE_URL/private/`` to the authorized
 users of the ``admin`` instance, and to ``$BASE_URL/instances/$ID/private/`` to
 the authorized users of the instance ``$ID``.
 
 By default, the GNU Taler merchant backend simply requires the respective
 HTTP requests to include an "Authorization" header with a "Bearer" token
 set to the respective shared secret which must begin with "secret-token:"
 (following RFC 8959).
 
 Note that all of the other endpoints (without ``/private/``)
 are expected to be fully exposed to the Internet, and wallets may have to
 interact with those endpoints directly without client authentication.
 
 
 Status code remapping
 ---------------------
 
 Normal API usage leaks instance existence information.  Distinguishing between
 404 (Not found) and 403 (Forbidden) is useful for diagnostics.
 
 For higher security (by leaking less information), you can add the following
 fragment, which remaps all 404 response codes to 403.
 
 Nginx
 ^^^^^
 
 .. code-block:: nginx
 
       error_page 404 =403 /empty.gif;
 
 Apache
 ^^^^^^
 
 .. code-block:: apacheconf
 
        cond %{STATUS} =404
        set-status 403
 
 
 Customization
 =============
 
 Legal conditions for using the service
 --------------------------------------
 
 .. include:: frags/legal.rst
 
 .. _MerchantTemplateCustomization:
 
 Template Customization
 ----------------------
 
 The installation process will install various HTML templates to be served to
 trigger the wallet interaction. You may change those templates to your own
 design. The templating language used is `C implementation of mustache
 <https://gitlab.com/jobol/mustach>`__, and the templates are in the
 ``share/taler-merchant/templates/`` directory.
 The default templates are maintained directly in the merchant source tree
 under ``src/frontend/``.  They are self-contained HTML documents: their
 styles, scripts and image data are embedded, so serving them does not require
 a separate Web UI build or external runtime resources.
 
 The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the
 name of the template and ``$LANG`` is the 2-letter language code of the
 template. English templates must exist and will be used as a fallback.  If the
 browser (user-agent) has provided language preferences in the HTTP header and
 the respective language exists, the correct language will be automatically
 served.
 
 The following subsections give details about each of the templates. The
 subsection titles are the ``$NAME`` of the respective template.
 
 request_payment
 ^^^^^^^^^^^^^^^
 
 Page shown to request the user to make a payment.
 
 This template is instantiated using the following information:
 
   * taler_pay_uri: String; the ``taler://pay/`` URI that must be given
     to the wallet to initiate the payment
 
   * taler_pay_qrcode_svg: Image; an SVG image of the QR code with the
     ``taler_pay_uri``.
 
   * order_summary: String; a text summarizing the order
 
   * order_status_url: URL of the merchant backend where the order status
     can be found, useful for long-polling to check if the order has been paid
 
   * order_id: String; the merchant's identifier for the order
 
   * merchant_name: String; the configured display name of the merchant
     instance
 
   * order_amount: Optional amount; the amount to pay when the order has one
     payment option or the wallet has selected an option
 
   * multiple_payment_options: Boolean; true when the wallet must select one
     of multiple payment options and no single amount can be displayed yet
 
   * claimed: Boolean; true after a wallet has claimed the order but before
     payment has completed
 
   * pay_deadline: Timestamp; the deadline for completing the payment
 
 
 offer_refund
 ^^^^^^^^^^^^
 
 Page shown to offer a customer a refund.
 
 This template is instantiated using the following information:
 
   * taler_refund_uri: String; the ``taler://refund/`` URI that must be given
     to the wallet to initiate collection of the refund
 
   * taler_refund_qrcode_svg: Image; an SVG image of the QR code with the
     ``taler_refund_uri``.
 
   * refund_amount: Amount; how much did the merchant refund
 
   * refund_taken: Amount; how much did the customer already take back in refunds
 
   * order_summary: String; a text summarizing the order
 
   * refund_remaining: Amount; how much is still available for the wallet to
     collect
 
   * has_refund_taken: Boolean; true when part of the refund was already
     collected
 
   * order_id: String; the merchant's identifier for the order
 
   * merchant_name: String; the configured display name of the merchant
     instance
 
   * order_status_url: Authenticated URL of the merchant backend where the
     refund status can be long-polled
 
 
 
 show_order_details
 ^^^^^^^^^^^^^^^^^^
 
 Page shown to the user when they go back to the payment page but
 no payment is required and no refund is present.
 
 This template is instantiated using the following information:
 
   * order_summary: String; a text summarizing the order
 
   * contract_terms: Object; the full contract terms (should probably
     not be shown in full!)
 
   * refund_amount: Amount; how much did the merchant refund
 
   * refund_taken: Amount; how much did the customer already take back in refunds
 
   * order_amount: Amount; the amount paid for the selected payment option
 
   * order_id: String; the merchant's identifier for the order
 
   * merchant_name: String; the configured display name of the merchant
     instance
 
   * has_refund: Boolean; true when the merchant granted a refund for this
     order
 
   * fulfillment_message: Optional string; localized message to show after
     successful payment
 
   * fulfillment_url: Optional URL; destination where the customer can
     continue to the purchased product or service
 
 Static files
 ------------
 
 The merchant backend also has the ability to serve small static files
 under the ``/static/{FILENAME}`` endpoint.  This is used by the templating
 logic to load a CSS file, but you can also put other resources such as
 images or JavaScript.
 
 Internationalization
 --------------------
 
 Both templates and static files can be internationalized.  This is done
 by having the language of the resource be a part of the filename.
 For templates the format is ``{BASENAME}.{LANGUAGE}.must``.  The
 language is mandatory for templates, the default language is English (en).
 
 For static files, the format is ``{BASENAME}.{LANGUAGE}.{EXT}`` for
 internationalized files, and ``{BASENAME}.{EXT}`` for resources that do not
 support internationalization.  The HTTP client will always request
 ``/static/{BASENAME}.{EXT}``. If ``{BASENAME}.{EXT}`` exists, that resource is
 returned. Otherwise, an internationalized file based on the language
 preferences indicated by the browser is returned.
 
 Limitations
 -----------
 
 All of the static files must fit into memory and it must be possible for the
 process to hold open file handles for all of these files.  You may want
 to increase the ``ulimit`` of the ``taler-merchant-httpd`` process if you have
 many static files. Note that Mustach templates do not increase the number of
 open files.
 
 The backend determines the MIME type based on the file's extension. The list
 of supported extensions is hard-coded and includes common text and image
 formats.
 
 The current backend only provides a limited set of variables for the Mustach
 template expansion, and does not make use of scopes and other Mustach
 features.
 
 
 
 Upgrade procedure
 =================
 
 This section describes the general upgrade procedure.  Please see the release
 notes for your specific version to check if a particular release has special
 upgrade requirements.
 
 Please note that upgrades are ONLY supported for released version of the
 merchant. Attempting to upgrade from or to a version in Git is not supported
 and may result in subtle data loss.
 
 Debian packages do not migrate the database or restart Merchant on upgrade.
 The operator must coordinate the complete upgrade; leaving old processes running
 is not a way to defer migration, since a crash or runtime limit can start newly
 installed binaries against the old database.
 
 1. Stop all Merchant services **before installing the new packages**. On Debian,
    run ``sudo systemctl stop taler-merchant.target``. This includes workers,
    the HTTP service and socket, and the garbage-collection timer. If multiple
    machines share the database, stop the Merchant services on every machine.
 2. Back up the database using your PostgreSQL backup procedure.
 3. Install the new packages. Services remain stopped.
 4. Apply the migration. For the standard Debian installation using the default
    local PostgreSQL cluster, run:
 
    .. code-block:: console
 
       $ sudo taler-merchant-dbconfig
 
    This preserves the existing database and invokes ``taler-merchant-dbinit``
    as ``taler-merchant-httpd`` with
    ``/etc/taler-merchant/taler-merchant.conf``. Never use ``-r`` for an upgrade:
    it deletes the existing database.
 
    For remote databases or separately administered credentials, run
    ``taler-merchant-dbinit -c /path/to/merchant.conf`` as the database owner
    or designated migration identity instead. Ensure all required migration
    privileges are available; ``dbconfig`` grants permission to set
    ``session_replication_role`` but does not restore other revoked privileges.
 5. After migration succeeds, restore any normal-operation privilege restrictions
    and start the desired Merchant services. Use
    ``sudo systemctl start taler-merchant.target`` to start the complete group.
    If migration fails, keep all Merchant services stopped while resolving it.
 
 ``taler-merchant-dbconfig`` does not stop services, make backups, or restart
 services. Its successful completion only confirms the database setup/migration
 step. Installation without a configured database remains supported.
 
 Scheduled garbage collection (``taler-merchant-dbinit -g``) never initializes
 or upgrades the schema or replaces stored procedures. It requires a current
 schema and fails with a diagnostic if migration is needed.
 
 
 
 
 Advanced topics
 ===============
 
 taler-merchant-config
 ---------------------
 
 .. index:: taler-merchant-config
 
 .. include:: frags/using-taler-config.rst
 
 .. _MerchantDatabaseScheme:
 
 Database Scheme
 ---------------
 
 The merchant database must be initialized using ``taler-merchant-dbinit``.
 This tool creates the tables required by the Taler merchant to operate.
 The tool also allows you to reset the Taler merchant database, which is
 useful for test cases but should never be used in production. Finally,
 ``taler-merchant-dbinit`` has a function to garbage collect a database,
 allowing administrators to purge records that are no longer required.
 
 The database scheme used by the merchant looks as follows:
 
 .. image:: images/merchant-db.png
 
 Schema migrations and stored procedures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Merchant schema changes are delivered as contiguously numbered SQL patches
 and tracked through the shared ``versioning.sql`` mechanism.  Once a patch has
 been part of a release or deployed to production or staging, it is immutable;
 a correction requires another patch.  The merchant does not use the
 exchange's partition/shard master-table scheme.
 
 Runtime functions and procedures are collected in the generated
 ``procedures.sql`` and loaded after the numbered schema patches.  Changing a
 runtime procedure therefore does not alter the schema-patch version.  Table,
 index, constraint, or stored-data changes still require a numbered patch.
 Developers must update the procedure sources and regenerate the aggregate
 rather than editing an installed database or generated output directly.
 ``taler-merchant-dbinit`` is the supported installation and upgrade path.
 
 Statistics storage and operation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Merchant statistics are maintained transactionally by database triggers, so
 the statistics endpoints return current values rather than a periodically
 computed snapshot.  Amount-valued statistics are separated by currency.
 Operators can query amount and counter slugs as bucketed values, sliding
 intervals, or both through the ``statistics-read`` API endpoints documented in
 the Merchant API.
 
 Bucket metadata defines calendar ranges and the number of generations to
 retain.  Interval metadata defines monotonically increasing windows and their
 precision.  Old event slots may be coarsened to the precision of a larger
 window and are eventually removed by statistics garbage collection.  A
 missing old value can therefore mean that the deployment does not retain that
 granularity; clients must handle the API's ``410 Gone`` response.
 
 Developers adding a built-in statistic use the database procedures
 ``bump_number_bucket_stat``, ``bump_amount_bucket_stat``,
 ``bump_number_interval_stat``, ``bump_amount_interval_stat``,
 ``bump_number_stat``, and ``bump_amount_stat`` rather than updating statistics
 tables directly.  Reads of sliding intervals go through
 ``statistic_interval_number_get`` or ``statistic_interval_amount_get`` so that
 expiry and coarsening are applied consistently.  ``statistic_bucket_gc``
 removes expired buckets and event slots.
 
 Statistics schema changes follow the ordinary merchant database versioning
 and are installed or upgraded by ``taler-merchant-dbinit``.  Operators must not
 modify the core statistics tables or triggers outside that versioning process.
 
 Periodic report scheduling is a separate layer: configured report generators
 consume the stored statistics through the report APIs.  Operators must
 configure the generator section before scheduling it; an unconfigured program
 is reported as ``501 Not Implemented``.
 
 .. _MerchantBenchmarking:
 
 Benchmarking
 ------------
 
 The merchant codebase offers the ``taler-merchant-benchmark`` tool to populate
 the database with fake payments.  The main goal of the benchmarking tool is to
 serve as a starting point (!) for merchants that are interested in developing
 stress tests to see how far their infrastructure can scale. As is, it
 currently is not actually good at stressing the payment system.
 
 The ``taler-unified-setup.sh`` script can be used to launch all required
 services and clients. However, the resulting deployment is simplistic
 (everything on the local machine, one single-threaded process per service
 type) and not optimized for performance at all. However, this can still be
 useful to assess the performance impact of changes
 to the code or configuration.
 
 
 Various configuration files that can be used in the code snippets in this
 section can be found in the ``src/merchant-tools/`` directory of the
 merchant. These are generally intended as starting points.  Note that the
 configuration files ending in ``.edited`` are created by
 ``taler-unified-setup.sh`` and contain some options that are determined at
 runtime by the setup logic provided by ``taler-unified-setup.sh``.
 
 See :ref:`Taler Exchange Manual <Benchmark-choose-bank>` for how to use ``taler-unified-setup.sh`` to setup the system and in particular on how to specify the bank to be used.
 
 
 Running taler-merchant-benchmark
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can run the tool as follows:
 
 .. code-block:: console
 
     $ CONF=benchmark-rsa.conf
     $ taler-unified-setup.sh -emwt -c "$CONF" -f -u exchange-account-1
     $ time taler-merchant-benchmark ordinary -c "$CONF".edited -u exchange-account-1 -f -p 20
 
 The current tool has already a few options, but we expect that to deliver
 *relevant* results it will need to be customized to better reflect the
 workload of a particular merchant.  This customization would at this point
 likely involve writing (C) code.  We welcome contributions to make it easier
 to customize the benchmark and/or to cover more realistic workloads from the
 start.
 
 The tool takes all of the values it needs from the command line, with
 some of them being common to all subcommands:
 
 -  ``--exchange-account-section=SECTION`` Specifies which configuration
    section specifies the bank account for the exchange that
    should be used for the benchmark. For the example
    configuration above, the SECTION value provided must be
    ``exchange-account-exchange``.
 -  ``--fakebank`` Specifies that the benchmark should expect to interact
    with a fakebank (instead of libeufin).
 
 The tool comes with two operation modes: *ordinary*, and *corner*.
 The first just executes normal payments, meaning that it uses the
 ``admin`` instance and makes sure that all payments get aggregated. The
 second gives the chance to leave some payments unaggregated, and also to
 use merchant instances other than ``admin`` (which is, actually, the
 one used by default by the tool).
 
 .. note::
 
    The ability to drive the aggregation policy is useful for testing
    the back-office facility.
 
 Any subcommand is also equipped with the canonical ``--help`` option, so
 feel free to issue the following command in order to explore all the
 possibilities. For example:
 
 .. code-block:: console
 
    $ taler-merchant-benchmark corner --help
 
 will show all the options offered by the *corner* mode. Among the most
 interesting, there are:
 
 -  ``--two-coins=TC`` This option instructs the tool to perform *TC*
    many payments that use two coins, because normally only one coin is
    spent per payment.
 
 -  ``--unaggregated-number=UN`` This option instructs the tool to
    perform *UN* (one coin) payments that will be left unaggregated.
 
 As for the ``ordinary`` subcommand, it is worth explaining the following
 option:
 
 -  ``--payments-number=PN`` Instructs the tool to perform *PN* payments.
 
 
 
 Temporarily Abandoned Features
 ==============================
 
 .. [1]
    https://docs.docker.com/
 
 
 Installing Taler using Docker
 -----------------------------
 
 This section provides instructions for the merchant backend installation
 using ‘Docker‘.
 
 For security reasons, we run Docker against a VirtualBox instance, so
 the ``docker`` command should connect to a ``docker-machine`` instance
 that uses the VirtualBox driver.
 
 Therefore, the needed tools are: “docker“, “docker-machine“, and
 “docker-compose“. Please refer to Docker’s official  [1]_ documentation
 in order to get those components installed, as that is not in this
 manual’s scope.
 
 Before starting to build the merchant’s image, make sure a
 “docker-machine“ instance is up and running.
 
 Because all of the Docker source file are kept in our “deployment“
 repository, we start by checking out the ``git://git.taler.net/deployment``
 codebase:
 
 .. code-block:: console
 
    $ git clone git://git.taler.net/deployment
 
 Now we actually build the merchant’s image. From the same directory as
 above:
 
 .. code-block:: console
 
    $ cd deployment/docker/merchant/
    $ docker-compose build
 
 If everything worked as expected, the merchant is ready to be launched.
 From the same directory as the previous step:
 
 .. code-block:: console
 
    # Recall: the docker-machine should be up and running.
    $ docker-compose up
 
 You should see some live logging from all the involved containers. At
 this stage of development, you should also ignore some (harmless) error
 message from postresql about already existing roles and databases.
 
 To test if everything worked as expected, it suffices to issue a simple
 request to the merchant, for example:
 
 .. code-block:: console
 
    $ wget -O - http://$(docker-machine ip)/
    # A greeting message should be returned by the merchant.