path: root/texinfo/taler-merchant.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename taler-merchant.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 5.3.0.@*
@end ifinfo
@settitle Taler Merchant Manual
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory CATEGORY
@direntry
* MENU ENTRY: (taler-merchant.info). DESCRIPTION
@end direntry

@c %**end of header

@copying
@quotation
GNU Taler 0.9.0, Jan 06, 2024

GNU Taler team

Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
@end quotation

@end copying

@titlepage
@title Taler Merchant Manual
@insertcopying
@end titlepage
@contents

@c %** start of user preamble

@c %** end of user preamble

@ifnottex
@node Top
@top Taler Merchant Manual
@insertcopying
@end ifnottex

@c %**start of body
@anchor{taler-merchant-manual doc}@anchor{0}
@c This file is part of GNU TALER.
@c 
@c Copyright (C) 2014-2023 Taler Systems SA
@c 
@c TALER is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
@c 
@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
@c 
@c You should have received a copy of the GNU Affero General Public License along with
@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
@c 
@c @author Christian Grothoff

@menu
* Introduction:: 
* Terminology:: 
* Installation:: 
* How to configure the merchant’s backend:: 
* Instance setup:: 
* Secure setup:: 
* Customization:: 
* Upgrade procedure:: 
* Advanced topics:: 
* Temporarily Abandoned Features:: 
* Index:: 

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* About GNU Taler:: 
* About this manual:: 
* Architecture overview:: 

Terminology

* Instances:: 
* Instance Bank Accounts:: 
* Inventory:: 
* Orders and Contracts:: 
* Transfers:: 
* Rewards:: 
* Reserves:: 

Installation

* Installing from source:: 
* Installing the GNU Taler binary packages on Debian:: 
* Installing the GNU Taler binary packages on Trisquel:: 
* Installing the GNU Taler binary packages on Ubuntu:: 

How to configure the merchant’s backend

* Configuration format:: 
* Backend options:: 
* Sample backend configuration:: 
* Launching the backend:: 

Backend options

* Service address:: 
* Currency:: 
* Database:: 
* Exchange:: 

Instance setup

* Setup without the Web interface:: 
* Accounts:: 
* Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. 
* Automatic Settlement Data Import:: 

Secure setup

* Using UNIX domain sockets:: 
* Reverse proxy configuration:: 
* Access control:: 
* Status code remapping:: 

Reverse proxy configuration

* Nginx:: 
* Apache:: 

Status code remapping

* Nginx: Nginx<2>. 
* Apache: Apache<2>. 

Customization

* Legal conditions for using the service:: 
* Terms of Service:: 
* Privacy Policy:: 
* Legal policies directory layout:: 
* Generating the Legal Terms:: 
* Adding translations:: 
* Updating legal documents:: 
* Mustach HTML Templates:: 
* Static files:: 
* Internationalization:: 
* Limitations:: 

Legal policies directory layout

* Example:: 

Advanced topics

* taler-config:: 
* Using taler-config:: 
* Database Scheme:: 
* Benchmarking:: 

Benchmarking

* Running taler-merchant-benchmark:: 

Temporarily Abandoned Features

* Installing Taler using Docker:: 

@end detailmenu
@end menu

@node Introduction,Terminology,Top,Top
@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{1}@anchor{taler-merchant-manual introduction}@anchor{2}@anchor{taler-merchant-manual taler-merchant-backend-operator-manual}@anchor{3}
@chapter Introduction


@menu
* About GNU Taler:: 
* About this manual:: 
* Architecture overview:: 

@end menu

@node About GNU Taler,About this manual,,Introduction
@anchor{taler-merchant-manual about-gnu-taler}@anchor{4}
@section About GNU Taler


@c This file is part of GNU TALER.
@c 
@c Copyright (C) 2014-2023 Taler Systems SA
@c 
@c TALER is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
@c 
@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
@c 
@c You should have received a copy of the GNU Affero General Public License along with
@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

GNU Taler is an open protocol for an electronic payment system with a
free software reference implementation. GNU Taler offers secure, fast
and easy payment processing using well understood cryptographic
techniques. GNU Taler allows customers to remain anonymous, while
ensuring that merchants can be held accountable by governments. Hence,
GNU Taler is compatible with anti-money-laundering (AML) and
know-your-customer (KYC) regulation, as well as data protection
regulation (such as GDPR).

@node About this manual,Architecture overview,About GNU Taler,Introduction
@anchor{taler-merchant-manual about-this-manual}@anchor{5}@anchor{taler-merchant-manual id1}@anchor{6}
@section 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.

This first chapter of the manual will give a brief overview of the
overall Taler architecture, describing the environment in which the
Taler backend operates. The second chapter then explains how to install
the software, including key dependencies. The third chapter will explain
how to configure the backend, including in particular the configuration
of the bank account details of the merchant.

The last chapter gives some additional information about advanced topics
which will be useful for system administrators but are not necessary for
operating a basic backend.

@node Architecture overview,,About this manual,Introduction
@anchor{taler-merchant-manual architecture-overview}@anchor{7}@anchor{taler-merchant-manual id2}@anchor{8}
@section Architecture overview


@geindex crypto-currency

@geindex 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.

@geindex frontend

@geindex back-office

@geindex backend

@geindex DBMS

@geindex PostgreSQL

The Taler software stack for a merchant consists of four main components:


@itemize -

@item 
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 gives an
introduction for how to integrate Taler with Web shop frontends.

@item 
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 Merchant Backend API provides
the API specification that should be reviewed to integrate such a
back-office with the Taler backend.

@item 
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.

@item 
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.
@end itemize

The following image illustrates the various interactions of these key
components:

@image{taler-merchant-figures/arch-api,,,,png}

@geindex 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 @code{/private/} and @code{/management/} API endpoints of the
merchant backend. Please carefully review the section on @ref{9,,secure setup} before deploying a Taler merchant backend into production.

@node Terminology,Installation,Introduction,Top
@anchor{taler-merchant-manual terminology}@anchor{a}
@chapter Terminology


This chapter describes some of the key concepts used throughout the manual.

@menu
* Instances:: 
* Instance Bank Accounts:: 
* Inventory:: 
* Orders and Contracts:: 
* Transfers:: 
* Rewards:: 
* Reserves:: 

@end menu

@node Instances,Instance Bank Accounts,,Terminology
@anchor{taler-merchant-manual instances}@anchor{b}
@section Instances


@geindex 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 (@code{/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').

@quotation

@cartouche
@quotation 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.
@end quotation
@end cartouche
@end quotation

@node Instance Bank Accounts,Inventory,Instances,Terminology
@anchor{taler-merchant-manual instance-bank-accounts}@anchor{c}
@section Instance Bank Accounts


@geindex instance-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 Taler Bank Revenue 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.

@node Inventory,Orders and Contracts,Instance Bank Accounts,Terminology
@anchor{taler-merchant-manual inventory}@anchor{d}
@section Inventory


@geindex inventory

@geindex product

@geindex lock

@geindex unit

@geindex 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.

@node Orders and Contracts,Transfers,Inventory,Terminology
@anchor{taler-merchant-manual orders-and-contracts}@anchor{e}
@section Orders and Contracts


@geindex order

@geindex terms

@geindex contract

@geindex claim

@geindex pay

@geindex refund

@geindex wire deadline

@geindex lock

@geindex 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 merchant API specification@footnote{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
@code{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 @code{taler-merchant-dbinit}.

@node Transfers,Rewards,Orders and Contracts,Terminology
@anchor{taler-merchant-manual transfers}@anchor{f}
@section Transfers


@geindex transfer

@geindex 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 Taler Bank Revenue 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.

@node Rewards,Reserves,Transfers,Terminology
@anchor{taler-merchant-manual rewards}@anchor{10}
@section Rewards


@geindex reward

@geindex pick up

Taler does not only allow a Website to be paid, but also to make voluntary,
non-contractual payments to visitors, called `rewards'.  Such rewards could be
granted as a reward for filling in surveys or watching advertizements. For
rewards, there is no contract, rewards are always voluntary actions by the Web
site that do not arise from a contractual obligation.  Before a Web site
can create rewards, it must establish a reserve.  Once a reserve has been
established, the merchant can `grant' rewards, allowing wallets to `pick up'
the reward.

@cartouche
@quotation Note 
Rewards are an optional feature, and exchanges may disable rewards (usually
if they see compliance issues). In this case, the reward feature will
not be available.
@end quotation
@end cartouche

@node Reserves,,Rewards,Terminology
@anchor{taler-merchant-manual reserves}@anchor{11}
@section Reserves


@geindex reserve

@geindex close

A `reserve' is a pool of electronic cash at an exchange under the control of
a private key.  Merchants withdraw coins from a reserve when granting
rewards.  A reserve is established by first generating the required key material
in the merchant backend, and then wiring the desired amount of funds to the
exchange.

An exchange will automatically `close' a reserve after a fixed period of time
(typically about a month), wiring any remaining funds back to the merchant.
While exchange APIs exists to (1) explicitly `open' a reserve to prevent it
from being automatically closed and to (2) explicitly `close' a reserve at any
time, the current merchant backend does not make use of these APIs.

@node Installation,How to configure the merchant’s backend,Terminology,Top
@anchor{taler-merchant-manual installation}@anchor{12}
@chapter Installation


This chapter describes how to install the GNU Taler merchant backend.

@menu
* Installing from source:: 
* Installing the GNU Taler binary packages on Debian:: 
* Installing the GNU Taler binary packages on Trisquel:: 
* Installing the GNU Taler binary packages on Ubuntu:: 

@end menu

@node Installing from source,Installing the GNU Taler binary packages on Debian,,Installation
@anchor{taler-merchant-manual generic-instructions}@anchor{13}@anchor{taler-merchant-manual installing-from-source}@anchor{14}
@section Installing from source


The following instructions will show how to install a GNU Taler
merchant backend from source.

The package sources can be find in our
download directory@footnote{http://ftpmirror.gnu.org/taler/}.

@c This file is part of GNU TALER.
@c 
@c Copyright (C) 2014-2023 Taler Systems SA
@c 
@c TALER is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
@c 
@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
@c 
@c You should have received a copy of the GNU Affero General Public License along with
@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
@c 
@c @author Christian Grothoff

GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format.
The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match.
Exceptions to this general rule are documented in the release notes.
For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x
as the MAJOR version matches.  A MAJOR version of 0 indicates experimental
development, and you are expected to always run all of the `latest' releases
together (no compatibility guarantees).

First, the following packages need to be installed before we can compile the
backend:


@itemize -

@item 
"Sphinx RTD Theme" Python package aka @code{python3-sphinx-rtd-theme}
on Debian-based systems (for GNUnet documentation support, can be
omitted if GNUnet is configured with @code{--disable-documentation})

@item 
libsqlite3 >= 3.16.2

@item 
GNU libunistring >= 0.9.3

@item 
libcurl >= 7.26 (or libgnurl >= 7.26)

@item 
libqrencode >= 4.0.0 (Taler merchant only)

@item 
GNU libgcrypt >= 1.6 (1.10 or later highly recommended)

@item 
libsodium >= 1.0

@item 
libargon2 >= 20171227

@item 
libjansson >= 2.7

@item 
PostgreSQL >= 15, including libpq

@item 
GNU libmicrohttpd >= 0.9.71

@item 
GNUnet >= 0.20 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/})

@item 
Python3 with @code{jinja2}
@end itemize

If you are on Debian stable or later, the following command may help you
install these dependencies:

@example
# apt-get install \
  libqrencode-dev \
  libsqlite3-dev \
  libltdl-dev \
  libunistring-dev \
  libsodium-dev \
  libargon2-dev \
  libcurl4-gnutls-dev \
  libgcrypt20-dev \
  libjansson-dev \
  libpq-dev \
  libmicrohttpd-dev \
  python3-jinja2 \
  postgresql-15
@end example

Before you install GNUnet, you must download and install the dependencies
mentioned in the previous section, otherwise the build may succeed, but could
fail to export some of the tooling required by GNU Taler.

On Ubuntu, you also need to install pkg-config, for example:

@example
$ apt-get install pkg-config
@end example

To install GNUnet, unpack the tarball and change
into the resulting directory, then proceed as follows:

@example
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
# ldconfig
@end example

If you did not specify a prefix, GNUnet will install to @code{/usr/local},
which requires you to run the last step as @code{root}.
The @code{ldconfig} command (also run as @code{root}) makes the
shared object libraries (@code{.so} files)
visible to the various installed programs.

Please note that unlike most packages, if you want to run the @code{make check}
command, you should run it only `after' having done @code{make install}.  The
latter ensures that necessary binaries are copied to the right place.

In any case, if @code{make check} fails, please consider filing a
bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.

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!

After installing GNUnet, unpack the GNU Taler exchange tarball,
change into the resulting directory, and proceed as follows:

@example
$ ./configure [--prefix=EXCHANGEPFX] \
              [--with-gnunet=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
@end example

If you did not specify a prefix, the exchange will install to @code{/usr/local},
which requires you to run the last step as @code{root}.  You have to specify
@code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/usr/local} in the
previous step.

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!

Please note that unlike most packages, if you want to run the @code{make check}
command, you should run it only `after' having done @code{make install}.  The
latter ensures that necessary binaries are copied to the right place.

In any case, if @code{make check} fails, please consider filing a
bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.

The following steps assume all dependencies are installed.

First, unpack the GNU Taler merchant tarball and change into
the resulting directory.
Then, use the following commands to build and install the merchant backend:

@example
$ ./configure [--prefix=PFX] \
              [--with-gnunet=GNUNETPFX] \
              [--with-exchange=EXCHANGEPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
@end example

If you did not specify a prefix, the exchange will install to
@code{/usr/local}, which requires you to run the last step as @code{root}.

You have to specify @code{--with-exchange=/usr/local} and/or
@code{--with-gnunet=/usr/local} if you installed the exchange and/or
GNUnet to @code{/usr/local} in the previous steps.

Depending on the prefixes you specified for the installation and the
distribution you are using, you may have to edit @code{/etc/ld.so.conf}, adding
lines for @code{GNUNETPFX/lib/} and @code{EXCHANGEPFX/lib/} and @code{PFX/lib/}
(replace the prefixes with the actual paths you used). Afterwards, you should
run @code{ldconfig}. Without this step, it is possible that the linker may not
find the installed libraries and launching the Taler merchant backend would
then fail.

Please note that unlike most packages, if you want to run the @code{make check}
command, you should run it only `after' having done @code{make install}.  The
latter ensures that necessary binaries are copied to the right place.

In any case, if @code{make check} fails, please consider filing a
bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.

@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Installing from source,Installation
@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{15}
@section Installing the GNU Taler binary packages on Debian


To install the GNU Taler Debian packages, first ensure that you have
the right Debian distribution. At this time, the packages are built for
Debian bookworm.

You need to add a file to import the GNU Taler packages. Typically,
this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that
looks like this:

@example
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main
@end example

Next, you must import the Taler Systems SA public package signing key
into your keyring and update the package lists:

@example
# wget -O /etc/apt/keyrings/taler-systems.gpg \
    https://taler.net/taler-systems.gpg
# apt update
@end example

@cartouche
@quotation Note 
You may want to verify the correctness of the Taler Systems SA key out-of-band.
@end quotation
@end cartouche

Now your system is ready to install the official GNU Taler binary packages
using apt.

To install the Taler merchant backend, you can now simply run:

@example
# apt install taler-merchant
@end example

Note that the package does not complete the integration of the backend with
the HTTP reverse proxy (typically with TLS certificates).  A configuration
fragment for Nginx or Apache will be placed in
@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}.  You must
furthermore still configure the database and the instances, and may need to
extend the fragment with access control restrictions for non-default
instances.

@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation
@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{16}
@section Installing the GNU Taler binary packages on Trisquel


To install the GNU Taler Trisquel packages, first ensure that you have
the right Trisquel distribution. Packages are currently available for
Trisquel GNU/Linux 10.0.  Simply follow the same instructions provided
for Ubuntu.

@node Installing the GNU Taler binary packages on Ubuntu,,Installing the GNU Taler binary packages on Trisquel,Installation
@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{17}
@section Installing the GNU Taler binary packages on Ubuntu


To install the GNU Taler Ubuntu packages, first ensure that you have
the right Ubuntu distribution. At this time, the packages are built for
Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your
@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages
from Ubuntu @code{universe}.

A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup
would look like this for Ubuntu Lunar:

@example
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar
@end example

For Ubuntu Jammy use this instead:

@example
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ jammy taler-jammy
@end example

The last line is crucial, as it adds the GNU Taler packages.

Next, you must import the Taler Systems SA public package signing key
into your keyring and update the package lists:

@example
# wget -O /etc/apt/keyrings/taler-systems.gpg \
    https://taler.net/taler-systems.gpg
# apt update
@end example

@cartouche
@quotation Note 
You may want to verify the correctness of the Taler Systems key out-of-band.
@end quotation
@end cartouche

Now your system is ready to install the official GNU Taler binary packages
using apt.

To install the Taler merchant backend, you can now simply run:

@example
# apt install taler-merchant
@end example

Note that the package does not complete the integration of the backend with
the HTTP reverse proxy (typically with TLS certificates).  A configuration
fragment for Nginx or Apache will be placed in
@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}.  You must
furthermore still configure the database and the instances, and may need to
extend the fragment with access control restrictions for non-default
instances.

@node How to configure the merchant’s backend,Instance setup,Installation,Top
@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{18}
@chapter How to configure the merchant’s backend


@geindex taler.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
@code{$HOME/.config/taler.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 @code{/etc/taler/taler.conf} as the main configuration file.

@menu
* Configuration format:: 
* Backend options:: 
* Sample backend configuration:: 
* Launching the backend:: 

@end menu

@node Configuration format,Backend options,,How to configure the merchant’s backend
@anchor{taler-merchant-manual configuration-format}@anchor{19}
@section Configuration format


All GNU Taler components are designed to possibly share the same
configuration files.  When installing a GNU Taler component, the
installation deploys default values in configuration files located
at $@{prefix@}/share/taler/config.d/ where $@{prefix@} is the installation
prefix. Different components must be installed to the same prefix.

In order to override these defaults, the user can write a custom configuration
file and either pass it to the component at execution time using the `-c'
option, or name it taler.conf and place it under $HOME/.config/ which is where
components will look by default. Note that the systemd service files pass @code{-c
/etc/taler/taler.conf}, thus making @code{/etc/taler/taler.conf}
the primary location for the configuration.

A config file is a text file containing sections, and each section
contains maps options to their values.  Configuration files follow
basically the INI syntax:

@example
[section1]
value1 = string
value2 = 23

[section2]
value21 = string
value22 = /path22
@end example

Comments start with a hash (@code{#}).  Throughout the configuration, it is
possible to use @code{$}-substitution for options relating to names of files or
directories. It is also possible to provide defaults values for those
variables that are unset, by using the following syntax:
@code{$@{VAR:-default@}}. There are two ways a user can set the value
of @code{$}-prefixable variables:

@quotation


@enumerate 

@item 
by defining them under a @code{[paths]} section:
@end enumerate

@quotation

@example
[paths]
TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
..
[section-x]
path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
@end example
@end quotation


@enumerate 2

@item 
or by setting them in the environment:
@end enumerate

@quotation

@example
$ export VAR=/x
@end example
@end quotation
@end quotation

The configuration loader will give precedence to variables set under
@code{[path]} over environment variables.

The utility @code{taler-config}, which gets installed along with the exchange,
can be used get and set configuration values without directly editing the
configuration file. The option @code{-f} is particularly useful to resolve
pathnames, when they use several levels of @code{$}-expanded variables. See
@code{taler-config --help}.

The repository @code{git://git.taler.net/deployment} contains example code
for generating configuration files under @code{deployment/netzbon/}.

@node Backend options,Sample backend configuration,Configuration format,How to configure the merchant’s backend
@anchor{taler-merchant-manual backend-options}@anchor{1a}@anchor{taler-merchant-manual id3}@anchor{1b}
@section Backend options


@geindex DBMS

@geindex PostgreSQL

@geindex UNIX domain socket

@geindex TCP

@geindex port

@geindex currency

@geindex KUDOS

@geindex exchange

@geindex instance

@geindex wire format

The following table describes the options that commonly need to be
modified. Here, the notation @code{[$SECTION]/$OPTION} denotes the option
@code{$OPTION} under the section @code{[$SECTION]} in the configuration file.

@menu
* Service address:: 
* Currency:: 
* Database:: 
* Exchange:: 

@end menu

@node Service address,Currency,,Backend options
@anchor{taler-merchant-manual service-address}@anchor{1c}
@subsection 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:

@example
[MERCHANT]
SERVE = unix # or tcp
@end example

If this option is set to


@itemize -

@item 
@code{tcp} then we need to set the TCP port in @code{[MERCHANT]/PORT};

@item 
@code{unix} then we need to set the unix domain socket path and mode
in @code{[MERCHANT]/UNIXPATH} and @code{[MERCHANT]/UNIXPATH_MODE}. The
latter takes the usual permission mask given as a number, e.g. 660
for user/group read-write access.
@end itemize

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 8888, use:

@example
[MERCHANT]
SERVE = tcp
PORT = 8888
@end example

@cartouche
@quotation Note 
If you need to change where the taler-merchant-httpd listens for requests,
you should edit @code{/etc/taler/merchant-overrides.conf}.  By default, the
Taler merchant package will use a UNIX domain socket at
@code{/run/taler/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 @code{/etc/taler/conf.d/merchant.conf}
configuration file.  Suitable reverse proxy configuration
file templates (@code{taler-merchant}) are be installed in the
respective @code{sites-available} directories of Apache and Nginx.
@end quotation
@end cartouche

@node Currency,Database,Service address,Backend options
@anchor{taler-merchant-manual currency}@anchor{1d}
@subsection Currency


Which currency the Web shop deals in, i.e. “EUR” or “USD”, is
specified using the option

@example
[TALER]
CURRENCY = EUR # or USD, ...
@end example

When testing with the Taler demonstration exchange at
@indicateurl{https://exchange.demo.taler.net/} you must set this
value to @code{KUDOS}:

@example
[TALER]
CURRENCY = KUDOS
@end example

@cartouche
@quotation Note 
When using the Debian/Ubuntu packages, these options should be
configured in the @code{/etc/taler/taler.conf} configuration file
(alternatively, you can also edit @code{/etc/taler/merchant-overrides.conf}).
However, you must edit the @code{taler.conf} file manually and `must not'
use @code{taler-config} to do this, as that would inline the include
directives and destroy the carefully setup path structure.
@end quotation
@end cartouche

@node Database,Exchange,Currency,Backend options
@anchor{taler-merchant-manual database}@anchor{1e}
@subsection Database


In principle it is possible for the backend to support different DBMSs.
The option

@example
[MERCHANT]
DB = postgres
@end example

specifies which DBMS is to be used. However, currently only the value
@code{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.

@cartouche
@quotation 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.
@end quotation
@end cartouche

For the @code{postgres} backend, you need to specify:

@example
[merchantdb-postgres]
CONFIG = "postgres:///taler-merchant"
@end example

This option specifies a PostgreSQL access path, typicallly using the format
@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the PostgreSQL
database you want to use (here, @code{taler-merchant} on the local machine).
Suppose @code{$USER} is the name of the user who will run the backend process
(usually @code{taler-merchant-httpd}). Then, you need to first run:

@example
$ sudo -u postgres createuser -d $USER
@end example

as the PostgreSQL database administrator (usually @code{postgres}) to
grant @code{$USER} the ability to create new databases. Next, you should
as @code{$USER} run:

@example
$ createdb $DBNAME
@end example

to create the backend’s database. Here, @code{$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
@code{$USER} (usually @code{taler-merchant-httpd}):

@example
$ taler-merchant-dbinit
@end example

You may improve your security posture if you now REVOKE the rights to CREATE,
DROP or ALTER tables from @code{$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.

@cartouche
@quotation Note 
Taler may store sensitive business and customer data in the database.  Any
operator SHOULD thus ensure that backup operations are encrypted and
secured from unauthorized access.
@end quotation
@end cartouche

@c index: MASTER_KEY

@node Exchange,,Database,Backend options
@anchor{taler-merchant-manual exchange}@anchor{1f}
@subsection 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:


@itemize -

@item 
The @code{EXCHANGE_BASE_URL} option specifies the exchange’s base URL.
For example, to use the Taler demonstrator, specify:

@example
[merchant-exchange-kudos]
EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/"
@end example

@item 
The @code{MASTER_KEY} option specifies the exchange’s master public key
in base32 encoding. For the Taler demonstrator, use:

@example
[merchant-exchange-kudos]
MASTER_KEY = "GNRJCH0HYKN59939JC0CJ2JDC7ZNEBSATJFF00CVS3WPG4TQEA7G"
@end example
@end itemize

@quotation

You can find out this key by running @code{curl https://exchange.demo.taler.net/keys | jq .master_public_key}.
@end quotation


@itemize -

@item 
The @code{CURRENCY} option specifies the exchange’s currency.
For the Taler demonstrator, use:

@example
[merchant-exchange-kudos]
CURRENCY = "KUDOS"
@end example
@end itemize

Note that multiple exchanges can be added to the system by using different
identifiers in place of @code{KUDOS} in the example above. Note that all of the
exchanges actually used will use the same currency: If the currency does not
match the main @code{CURRENCY} option from the @code{taler} section, the respective
@code{merchant-exchange-} section is automatically ignored. If you need support
for multiple currencies, you need to deploy one backend per currency.

The merchant already ships with a default configuration that contains the
@code{merchant-exchange-kudos} section from above.

@cartouche
@quotation 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.
@end quotation
@end cartouche

@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend
@anchor{taler-merchant-manual id4}@anchor{20}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{21}
@section Sample backend configuration


@geindex configuration

The following is an example for a complete backend configuration:

@example
[taler]
CURRENCY = KUDOS

[merchant]
SERVE = TCP
PORT = 8888
DATABASE = postgres

[merchantdb-postgres]
CONFIG = postgres:///donations

[merchant-exchange-kudos]
EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
# If currency does not match [taler] section, the exchange
# will be ignored!
CURRENCY = KUDOS
@end example

Given the above configuration, the backend will use a PostgreSQL database
named @code{donations} running on the same host.

The backend will deposit the coins it receives to the exchange at
@indicateurl{https://exchange.demo.taler.net/}, which has the master key
@code{FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0}.

@node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend
@anchor{taler-merchant-manual id5}@anchor{22}@anchor{taler-merchant-manual launching-the-backend}@anchor{23}
@section Launching the backend


@geindex backend

@geindex taler-merchant-httpd

Assuming you have configured everything correctly, you can launch the
merchant backend as @code{$USER} using

@example
$ taler-merchant-httpd &
$ taler-merchant-webhook &
$ taler-merchant-wirewatch &
@end example

You only need to run @code{taler-merchant-webhook} if one of the instances is
configured to trigger web hooks.  Similarly, @code{taler-merchant-wirewatch} is
only required if instances have accounts configured with automatic import of
wire transfers via a bank wire gateway.

To ensure these processes runs 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 exhausing the memory utilization of the
PostgreSQL database.  Consult the documentation of your operating system for
how to start and stop daemons.

@cartouche
@quotation Note 
When using the Debian/Ubuntu packages, the systemd configuration
will already exist. You only need to enable and start the service
using @code{systemctl enable taler-merchant-httpd} and
@code{systemctl start taler-merchant-httpd}. Additionally, you should
review the @code{/etc/apache2/sites-available/taler-merchant.conf}
or @code{/etc/nginx/sites-available/taler-merchant} (these files
contain additional instructions to follow), symlink it to
@code{sites-enabled/} and restart your HTTP server. After that, you
should be able to visit the merchant backend at the respective
HTTP(S) endpoint.
@end quotation
@end cartouche

If everything worked as expected, the command

@example
$ wget -O - http://localhost:8888/config
@end example

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:

@quotation


@itemize *

@item 
Use the @code{--auth=$TOKEN} command-line option to set an access token to be provided in an @code{Authorize: 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.

@item 
Set the @code{TALER_MERCHANT_TOKEN} environment variable to @code{$TOKEN} for the same effect. This method has the advantage of @code{$TOKEN} not being visible as a command-line interface to other local users on the same machine.

@item 
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!
@end itemize
@end quotation

Production systems should additionally be configured to bind to a UNIX domain socket
and use TLS for improved network privacy, see @ref{9,,Secure setup}.

@geindex instance

@node Instance setup,Secure setup,How to configure the merchant’s backend,Top
@anchor{taler-merchant-manual id6}@anchor{24}@anchor{taler-merchant-manual instance-setup}@anchor{25}
@chapter Instance setup


First of all, 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 instead of the @code{wget} commands given
below.

Regardless of which tool you use, the first step for using the backend
involves the creation of a @code{default} instance. The @code{default} instance can
also create / delete / configure other instances, similar to the @code{root}
account on UNIX.  When no instance exists and @code{taler-merchant-httpd} was
started without the @code{--auth} option, then the backend is reachable without
any access control (unless you configured some in the reverse proxy).

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.

@cartouche
@quotation 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 is concern can be addressed using a properly configured
@ref{26,,reverse proxy}.
@end quotation
@end cartouche

@menu
* Setup without the Web interface:: 
* Accounts:: 
* Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. 
* Automatic Settlement Data Import:: 

@end menu

@node Setup without the Web interface,Accounts,,Instance setup
@anchor{taler-merchant-manual setup-without-the-web-interface}@anchor{27}
@section Setup without the Web interface


Instances can be created by POSTing a request to @code{/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 @code{instance.json} with an
InstanceConfigurationMessage:

@example
@{
  "id" : "default",
  "name": "example.com",
  "address": @{ "country" : "zz" @},
  "auth": @{ "method" : "external"@} ,
  "jurisdiction": @{ "country" : "zz" @},
  "use_stefan": true,
  "default_wire_transfer_delay": @{ "d_ms" : 1209600000 @},
  "default_pay_delay": @{ "d_ms" : 1209600000 @}
@}
@end example

The @code{name} field will be shown as the name of your shop. The
@code{address} field is expected to contain your shop's physical address. The
various defaults 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
contract terms specification.

You can then create the instance using:

@example
$ wget --post-file=instance.json http://localhost:8888/management/instances
@end example

The base URL for the instance will then be
@code{http://localhost:8888/instances/default}.  You can create additional
instances by changing the @code{id} value to identifies other than @code{default}.

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 Merchant Backend API documentation.

@node Accounts,Detecting Settlement Manually Adding Transfers,Setup without the Web interface,Instance setup
@anchor{taler-merchant-manual accounts}@anchor{28}
@section Accounts


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.

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. Specifying the revenue gateway
with username and password is optional and discussed below.

@node Detecting Settlement Manually Adding Transfers,Automatic Settlement Data Import,Accounts,Instance setup
@anchor{taler-merchant-manual detecting-settlement-manually-adding-transfers}@anchor{29}
@section Detecting Settlement: Manually Adding Transfers


The exchange may aggregate many small amounts into one larger wire transfer.
If you want to safely determine for 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.

@node Automatic Settlement Data Import,,Detecting Settlement Manually Adding Transfers,Instance setup
@anchor{taler-merchant-manual automatic-settlement-data-import}@anchor{2a}
@section Automatic Settlement Data Import


To automatically import settlement data, you can provide the merchant backend
with the address and access credentials of a Taler revenue API for each bank
account of an instance.  The revenue API endpoint will allow the merchant
backend to observe all incoming wire transfers into your bank account and
automatically import them into the list of wire transfers.

Note that setting up a revenue API endpoint will usually require you to first
ask your bank for EBICS access and to setup libeufin to provide the revenue
API endpoint. The taler-bank used by regional currency setups also provides
a revenue API endpoint.

@node Secure setup,Customization,Instance setup,Top
@anchor{taler-merchant-manual id7}@anchor{2b}@anchor{taler-merchant-manual secure-setup}@anchor{9}
@chapter Secure setup


@geindex security

@geindex TLS

The Taler backend does not include even the most basic forms of access control
or transport layer security.  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.

@menu
* Using UNIX domain sockets:: 
* Reverse proxy configuration:: 
* Access control:: 
* Status code remapping:: 

@end menu

@node Using UNIX domain sockets,Reverse proxy configuration,,Secure setup
@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{2c}
@section 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:

@example
[MERCHANT]
SERVE = unix
UNIXPATH = "/some/path/here.sock"
@end example

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".

@node Reverse proxy configuration,Access control,Using UNIX domain sockets,Secure setup
@anchor{taler-merchant-manual id8}@anchor{2d}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{26}
@section Reverse proxy configuration


@menu
* Nginx:: 
* Apache:: 

@end menu

@node Nginx,Apache,,Reverse proxy configuration
@anchor{taler-merchant-manual nginx}@anchor{2e}
@subsection Nginx


For Nginx, a possible basic reverse proxy configuration would be:

@example
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";
@end example

Note that the above assumes your domain name is @code{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 @code{taler-merchant-httpd}
process after changing the @code{SERVE} configuration.

@node Apache,,Nginx,Reverse proxy configuration
@anchor{taler-merchant-manual apache}@anchor{2f}
@subsection Apache


In Apache, make sure you have @code{mod_proxy}, @code{mod_proxy_http} and
@code{mod_headers} enabled:

@example
$ a2enmod proxy
$ a2enmod proxy_http
$ a2enmod headers
@end example

Then configure your Apache reverse proxy like this (you may change the
endpoint):

@example
<Location "/">
ProxyPass "unix:/some/path/here.sock|http://example.com/"
RequestHeader add "X-Forwarded-Proto" "https"
</Location>
@end example

Note that the above again assumes your domain name is @code{example.com} and that
you have TLS configured.  Note that you must add the @code{https} header unless
your site is not available via TLS.

@node Access control,Status code remapping,Reverse proxy configuration,Secure setup
@anchor{taler-merchant-manual access-control}@anchor{30}
@section Access control


All endpoints with @code{/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 @code{$BASE_URL/private/} to the authorized
users of the default instance, and to @code{$BASE_URL/instances/$ID/private/} to
the authorized users of the instance @code{$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 @code{/private/})
are expected to be fully exposed to the Internet, and wallets may have to
interact with those endpoints directly without client authentication.

@node Status code remapping,,Access control,Secure setup
@anchor{taler-merchant-manual status-code-remapping}@anchor{31}
@section 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.

@menu
* Nginx: Nginx<2>. 
* Apache: Apache<2>. 

@end menu

@node Nginx<2>,Apache<2>,,Status code remapping
@anchor{taler-merchant-manual id9}@anchor{32}
@subsection Nginx


@example
error_page 404 =403 /empty.gif;
@end example

@node Apache<2>,,Nginx<2>,Status code remapping
@anchor{taler-merchant-manual id10}@anchor{33}
@subsection Apache


@example
cond %@{STATUS@} =404
set-status 403
@end example

@node Customization,Upgrade procedure,Secure setup,Top
@anchor{taler-merchant-manual customization}@anchor{34}
@chapter Customization


@menu
* Legal conditions for using the service:: 
* Terms of Service:: 
* Privacy Policy:: 
* Legal policies directory layout:: 
* Generating the Legal Terms:: 
* Adding translations:: 
* Updating legal documents:: 
* Mustach HTML Templates:: 
* Static files:: 
* Internationalization:: 
* Limitations:: 

@end menu

@node Legal conditions for using the service,Terms of Service,,Customization
@anchor{taler-merchant-manual legal-conditions-for-using-the-service}@anchor{35}
@section Legal conditions for using the service


@c This file is part of GNU TALER.
@c 
@c Copyright (C) 2014-2023 Taler Systems SA
@c 
@c TALER is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
@c 
@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
@c 
@c You should have received a copy of the GNU Affero General Public License along with
@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
@c 
@c @author Christian Grothoff

The service has well-known API endpoints to return its legal conditions to the
user in various languages and various formats.  This section describes how to
setup and configure the legal conditions.

@node Terms of Service,Privacy Policy,Legal conditions for using the service,Customization
@anchor{taler-merchant-manual terms-of-service}@anchor{36}
@section Terms of Service


The service has an endpoint "/terms" to return the terms of service (in legal
language) of the service operator.  Client software show these terms of
service to the user when the user is first interacting with the service.
Terms of service are optional for experimental deployments, if none are
configured, the service will return a simple statement saying that there are
no terms of service available.

To configure the terms of service response, there are two options
in the configuration file for the service:


@itemize -

@item 
@code{TERMS_ETAG}: The current "Etag" to return for the terms of service.
This value must be changed whenever the terms of service are
updated. A common value to use would be a version number.
Note that if you change the @code{TERMS_ETAG}, you MUST also provide
the respective files in @code{TERMS_DIR} (see below).

@item 
@code{TERMS_DIR}: The directory that contains the terms of service.
The files in the directory must be readable to the service
process.
@end itemize

@node Privacy Policy,Legal policies directory layout,Terms of Service,Customization
@anchor{taler-merchant-manual privacy-policy}@anchor{37}
@section Privacy Policy


The service has an endpoint "/pp" to return the terms privacy policy (in legal
language) of the service operator.  Clients should show the privacy policy to
the user when the user explicitly asks for it, but it should not be shown by
default.  Privacy policies are optional for experimental deployments, if none
are configured, the service will return a simple statement saying that there
is no privacy policy available.

To configure the privacy policy response, there are two options
in the configuration file for the service:


@itemize -

@item 
@code{PRIVACY_ETAG}: The current "Etag" to return for the privacy policy.
This value must be changed whenever the privacy policy is
updated. A common value to use would be a version number.
Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide
the respective files in @code{PRIVACY_DIR} (see below).

@item 
@code{PRIVACY_DIR}: The directory that contains the privacy policy.
The files in the directory must be readable to the service
process.
@end itemize

@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Customization
@anchor{taler-merchant-manual legal-policies-directory-layout}@anchor{38}
@section Legal policies directory layout


The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a
particular layout.  You may use the same directory for both the terms of
service and the privacy policy, as long as you use different ETAGs.  Inside of
the directory, there should be sub-directories using two-letter language codes
like "en", "de", or "jp".  Each of these directories would then hold
translations of the current terms of service into the respective language.
Empty directories are permitted in case translations are not available.

Then, inside each language directory, files with the name of the value set as
the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each
of the files should be typical for the respective mime type.  The set of
supported mime types is currently hard-coded in the service, and includes
".epub", ".html", ".md", ".pdf" and ".txt" files. If other files are present,
the service may show a warning on startup.

@menu
* Example:: 

@end menu

@node Example,,,Legal policies directory layout
@anchor{taler-merchant-manual example}@anchor{39}
@subsection Example


A sample file structure for a @code{TERMS_ETAG} of "tos-v0" would be:


@itemize -

@item 
TERMS_DIR/en/tos-v0.txt

@item 
TERMS_DIR/en/tos-v0.html

@item 
TERMS_DIR/en/tos-v0.pdf

@item 
TERMS_DIR/en/tos-v0.epub

@item 
TERMS_DIR/en/tos-v0.md

@item 
TERMS_DIR/de/tos-v0.txt

@item 
TERMS_DIR/de/tos-v0.html

@item 
TERMS_DIR/de/tos-v0.pdf

@item 
TERMS_DIR/de/tos-v0.epub

@item 
TERMS_DIR/de/tos-v0.md
@end itemize

If the user requests an HTML format with language preferences "fr" followed by
"en", the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in
French.

@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Customization
@anchor{taler-merchant-manual generating-the-legal-terms}@anchor{3a}
@section Generating the Legal Terms


The @code{taler-terms-generator} script can be used to generate directories with
terms of service and privacy policies in multiple languages and all required
data formats from a single source file in @code{.rst} format and GNU gettext
translations in @code{.po} format.

To use the tool, you need to first write your legal conditions in English in
reStructuredText (rst).  You should find a templates in
@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you
installed the service to. Whenever you make substantive changes to the legal
terms, you must use a fresh filename and change the respective @code{ETAG}.  The
resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document.

Once you have written the @code{$ETAG.rst} file in English, you can
generate the first set of outputs:

@example
$ taler-terms-generator -i $ETAG
@end example

Afterwards, you should find the terms in various formats for all configured
languages (initially only English) in @code{$PREFIX/share/terms/}.  The generator
has a few options which are documented in its man page.

@node Adding translations,Updating legal documents,Generating the Legal Terms,Customization
@anchor{taler-merchant-manual adding-translations}@anchor{3b}
@section Adding translations


Translations must be available in subdirectories
@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}.
To start translating, you first need to add a new
language:

@example
$ taler-terms-generator -i $ETAG -l $LANGUAGE
@end example

Here, @code{$LANGUAGE} should be a two-letter language
code like @code{de} or @code{fr}.  The command will generate
a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}
which contains each English sentence or paragraph
in the original document and an initially empty
translation.  Translators should update the @code{.po}
file. Afterwards, simply re-run

@example
$ taler-terms-generator -i $ETAG
@end example

to make the current translation(s) available to the
service.

@cartouche
@quotation Note 
You must restart the service whenever adding or updating legal documents or their translations.
@end quotation
@end cartouche

@node Updating legal documents,Mustach HTML Templates,Adding translations,Customization
@anchor{taler-merchant-manual updating-legal-documents}@anchor{3c}
@section Updating legal documents


When making minor changes without legal implications, edit the @code{.rst} file,
then re-run the step to add a new language for each existing translation to
produce an updated @code{.po} file. Translate the sentences that have changed and
finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to
create the final files.

When making major changes with legal implications, you should first rename (or
copy) the existing @code{.rst} file and the associated translation files to a new
unique name.  Afterwards, make the major changes, update the @code{.po} files,
complete the translations and re-create the final files.  Finally, do not
forget to update the @code{ETAG} configuration option to the new name and to
restart the service.

@node Mustach HTML Templates,Static files,Updating legal documents,Customization
@anchor{taler-merchant-manual mustach-html-templates}@anchor{3d}
@section Mustach HTML Templates


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 Mustach, and the templates
are in the @code{share/taler/merchant/templates/} directory.

@node Static files,Internationalization,Mustach HTML Templates,Customization
@anchor{taler-merchant-manual static-files}@anchor{3e}
@section Static files


The merchant backend also has the ability to serve small static files
under the @code{/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.

@node Internationalization,Limitations,Static files,Customization
@anchor{taler-merchant-manual internationalization}@anchor{3f}
@section 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 @code{@{BASENAME@}.@{LANGUAGE@}.must}.  The
language is mandatory for templates, the default language is English (en).

For static files, the format is @code{@{BASENAME@}.@{LANGUAGE@}.@{EXT@}} for
internationalized files, and @code{@{BASENAME@}.@{EXT@}} for resources that do not
support internationalization.  The HTTP client will always request
@code{/static/@{BASENAME@}.@{EXT@}}. If @code{@{BASENAME@}.@{EXT@}} exists, that resource is
returned. Otherwise, an internationalized file based on the language
preferences indicated by the browser is returned.

@node Limitations,,Internationalization,Customization
@anchor{taler-merchant-manual limitations}@anchor{40}
@section 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 @code{ulimit} of the @code{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.

@node Upgrade procedure,Advanced topics,Customization,Top
@anchor{taler-merchant-manual upgrade-procedure}@anchor{41}
@chapter 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.

To safely upgrade the merchant, you should first stop the existing
@code{taler-merchant-httpd} process, backup your merchant database (see
PostgreSQL manual), and then install the latest version of the code.

If you REVOKED database permissions, ensure that the rights to CREATE,
DROP, and ALTER tables are GRANTed to @code{$USER} again.  Then, run:

@example
$ taler-merchant-dbinit
@end example

to upgrade the database to the latest schema.  After that, you may again
REVOKE the database permissions. Finally, restart the merchant services
processes, either via your systemd or init system, or directly.

@node Advanced topics,Temporarily Abandoned Features,Upgrade procedure,Top
@anchor{taler-merchant-manual advanced-topics}@anchor{42}
@chapter Advanced topics


@menu
* taler-config:: 
* Using taler-config:: 
* Database Scheme:: 
* Benchmarking:: 

@end menu

@node taler-config,Using taler-config,,Advanced topics
@anchor{taler-merchant-manual taler-config}@anchor{43}
@section taler-config


@geindex taler-config

@node Using taler-config,Database Scheme,taler-config,Advanced topics
@anchor{taler-merchant-manual using-taler-config}@anchor{44}
@section Using taler-config


The tool @code{taler-config} can be used to extract or manipulate configuration
values; however, the configuration use the well-known INI file format and is
generally better edited by hand to preserve comments and structure.  Thus, @code{taler-config} should primarily be used
to inspect or understand a configuration that is in place,
and not to update it!

Run

@example
$ taler-config -s $SECTION
@end example

to list all of the configuration values in section @code{$SECTION}.

Run

@example
$ taler-config -s $SECTION -o $OPTION
@end example

to extract the respective configuration value for option @code{$OPTION} in
section @code{$SECTION}.

Finally, to change a setting and clobber your entire
configuration file structure, inlining all values and
removing all comments, run

@example
$ taler-config -s $SECTION -o $OPTION -V $VALUE
@end example

to set the respective configuration value to @code{$VALUE}. Note that you
have to manually restart affected Taler components after you change the
configuration to make the new configuration go into effect.

Some default options will use $-variables, such as @code{$DATADIR} within
their value. To expand the @code{$DATADIR} or other $-variables in the
configuration, pass the @code{-f} option to @code{taler-config}. For example,
compare:

@example
$ taler-config --section exchange-offline --option MASTER_PRIV_FILE
$ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE
@end example

While the configuration file is typically located at
@code{$HOME/.config/taler.conf}, an alternative location can be specified to any
GNU Taler component using the @code{-c} option.

@node Database Scheme,Benchmarking,Using taler-config,Advanced topics
@anchor{taler-merchant-manual database-scheme}@anchor{45}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{46}
@section Database Scheme


The merchant database must be initialized using @code{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,
@code{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{taler-merchant-figures/merchant-db,,,,png}

@node Benchmarking,,Database Scheme,Advanced topics
@anchor{taler-merchant-manual benchmarking}@anchor{47}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{48}
@section Benchmarking


The merchant codebase offers the @code{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 @code{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 @code{src/merchant-tools/} directory of the
merchant. These are generally intended as starting points.  Note that the
configuration files ending in @code{.edited} are created by
@code{taler-unified-setup.sh} and contain some options that are determined at
runtime by the setup logic provided by @code{taler-unified-setup.sh}.

See Taler Exchange Manual for how to use @code{taler-unified-setup.sh} to setup the system and in particular on how to specify the bank to be used.

@menu
* Running taler-merchant-benchmark:: 

@end menu

@node Running taler-merchant-benchmark,,,Benchmarking
@anchor{taler-merchant-manual running-taler-merchant-benchmark}@anchor{49}
@subsection Running taler-merchant-benchmark


You can run the tool as follows:

@example
$ 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
@end example

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:


@itemize -

@item 
@code{--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
@code{exchange-account-exchange}.

@item 
@code{--fakebank} Specifies that the benchmark should expect to interact
with a fakebank (instead of libeufin).
@end itemize

The tool comes with two operation modes: `ordinary', and `corner'.
The first just executes normal payments, meaning that it uses the
default instance and make sure that all payments get aggregated. The
second gives the chance to leave some payments unaggregated, and also to
use merchant instances other than the default (which is, actually, the
one used by default by the tool).

Note: the ability of driving the aggregation policy is useful for testing
the back-office facility.

Any subcommand is also equipped with the canonical @code{--help} option, so
feel free to issue the following command in order to explore all the
possibilities. For example:

@example
$ taler-merchant-benchmark corner --help
@end example

will show all the options offered by the `corner' mode. Among the most
interesting, there are:


@itemize -

@item 
@code{--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.

@item 
@code{--unaggregated-number=UN} This option instructs the tool to
perform `UN' (one coin) payments that will be left unaggregated.
@end itemize

As for the @code{ordinary} subcommand, it is worth explaining the following
option:


@itemize -

@item 
@code{--payments-number=PN} Instructs the tool to perform `PN' payments.
@end itemize

@node Temporarily Abandoned Features,Index,Advanced topics,Top
@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{4a}
@chapter Temporarily Abandoned Features


@menu
* Installing Taler using Docker:: 

@end menu

@node Installing Taler using Docker,,,Temporarily Abandoned Features
@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{4b}
@section 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 @code{docker} command should connect to a @code{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  @footnote{
@indicateurl{https://docs.docker.com/}
} 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 @code{git://git.taler.net/deployment}
codebase:

@example
$ git clone git://git.taler.net/deployment
@end example

Now we actually build the merchant’s image. From the same directory as
above:

@example
$ cd deployment/docker/merchant/
$ docker-compose build
@end example

If everything worked as expected, the merchant is ready to be launched.
From the same directory as the previous step:

@example
# Recall: the docker-machine should be up and running.
$ docker-compose up
@end example

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:

@example
$ wget -O - http://$(docker-machine ip)/
# A greeting message should be returned by the merchant.
@end example

@node Index,,Temporarily Abandoned Features,Top
@unnumbered Index


@printindex ge


@c %**end of body
@bye