prebuilt: update

1 files changed, 1461 insertions, 0 deletions

diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi
new file mode 100644
index 00000000..f1334973
--- /dev/null
+++ b/texinfo/taler-merchant.texi
@@ -0,0 +1,1461 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename taler-merchant.info
+@documentencoding UTF-8
+@ifinfo
+@*Generated by Sphinx 2.2.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
+
+@definfoenclose strong,`,'
+@definfoenclose emph,`,'
+@c %**end of header
+
+@copying
+@quotation
+GNU Taler 0.6.0pre1, Sep 18, 2019
+
+GNU Taler team
+
+Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (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}
+@menu
+* Introduction:: 
+* Installation:: 
+* How to configure the merchant’s backend:: 
+* Testing:: 
+* Advanced topics:: 
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* About GNU Taler:: 
+* About this manual:: 
+* Architecture overview:: 
+
+Installation
+
+* Installing Taler using Docker:: 
+* Generic instructions:: 
+* Installing Taler on Debian GNU/Linux:: 
+
+Generic instructions
+
+* Installation of dependencies:: 
+* Installing libgnunetutil:: 
+* Installing the GNU Taler exchange:: 
+* Installing the GNU Taler merchant backend:: 
+
+How to configure the merchant’s backend
+
+* Backend options:: 
+* Sample backend configuration:: 
+* Launching the backend:: 
+
+Advanced topics
+
+* Configuration format:: 
+* Using taler-config:: 
+* Merchant key management:: 
+* Using the SEPA wire transfer method:: 
+* Tipping visitors:: 
+* Generate payments:: 
+
+Tipping visitors
+
+* Configure a reserve and exchange for tipping:: 
+* Fund the reserve:: 
+* Authorize a tip:: 
+* Picking up of the tip:: 
+
+@end detailmenu
+@end menu
+
+@node Introduction,Installation,Top,Top
+@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{1}@anchor{taler-merchant-manual introduction}@anchor{2}
+@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{3}
+@section About GNU Taler
+
+
+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).
+
+GNU Taler is not yet production-ready, after following this manual you
+will have a backend that can process payments in “KUDOS”, but not
+regular currencies. This is not so much because of limitations in the
+backend, but because we are not aware of a Taler exchange operator
+offering regular currencies today.
+
+@node About this manual,Architecture overview,About GNU Taler,Introduction
+@anchor{taler-merchant-manual about-this-manual}@anchor{4}@anchor{taler-merchant-manual id1}@anchor{5}
+@section About this manual
+
+
+This tutorial targets system administrators who want to install a GNU
+Taler merchant @emph{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 tutorial 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{6}@anchor{taler-merchant-manual id2}@anchor{7}
+@section Architecture overview
+
+
+crypto-currency
+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. For testing purposes, Taler uses a
+special currency “KUDOS” and includes its own special bank.
+
+The Taler software stack for a merchant consists of four main
+components:
+
+
+@itemize -
+
+@item 
+frontend
+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. This manual describes how to
+integrate Taler with Web shop frontends.
+
+@item 
+back office
+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
+again not included with Taler, but rather assumed to exist at the
+merchant. This manual will describe how to integrate such a component
+to handle payments managed by Taler.
+
+@item 
+backend
+A Taler-specific payment backend which makes it easy for the frontend
+to process financial transactions with Taler. The next two chapters
+will describe how to install and configure this backend.
+
+@item 
+DBMS
+Postgres
+A DBMS which stores the transaction history for the Taler backend.
+For now, the GNU Taler reference implemenation only supports
+Postgres, but the code could be easily extended to support another
+DBMS.
+@end itemize
+
+The following image illustrates the various interactions of these key
+components:
+
+@example
+Missing diagram image
+@end example
+
+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 is encapsulated within the Taler backend.
+
+@node Installation,How to configure the merchant’s backend,Introduction,Top
+@anchor{taler-merchant-manual installation}@anchor{8}
+@chapter Installation
+
+
+This chapter describes how to install the GNU Taler merchant backend.
+
+@menu
+* Installing Taler using Docker:: 
+* Generic instructions:: 
+* Installing Taler on Debian GNU/Linux:: 
+
+@end menu
+
+@node Installing Taler using Docker,Generic instructions,,Installation
+@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{9}
+@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{@w{(1)} 
+@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://taler.net/deployment}
+codebase:
+
+@example
+$ git clone 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, as:
+
+@example
+$ curl http://$(docker-machine ip)/
+# A greeting message should be returned by the merchant.
+@end example
+
+@node Generic instructions,Installing Taler on Debian GNU/Linux,Installing Taler using Docker,Installation
+@anchor{taler-merchant-manual generic-instructions}@anchor{a}@anchor{taler-merchant-manual id4}@anchor{b}
+@section Generic instructions
+
+
+This section provides generic instructions for the merchant backend
+installation independent of any particular operating system. Operating
+system specific instructions are provided in the following sections. You
+should follow the operating system specific instructions if those are
+available, and only consult the generic instructions if no
+system-specific instructions are provided for your specific operating
+system.
+
+@menu
+* Installation of dependencies:: 
+* Installing libgnunetutil:: 
+* Installing the GNU Taler exchange:: 
+* Installing the GNU Taler merchant backend:: 
+
+@end menu
+
+@node Installation of dependencies,Installing libgnunetutil,,Generic instructions
+@anchor{taler-merchant-manual id5}@anchor{c}@anchor{taler-merchant-manual installation-of-dependencies}@anchor{d}
+@subsection Installation of dependencies
+
+
+The following packages need to be installed before we can compile the
+backend:
+
+
+@itemize -
+
+@item 
+autoconf >= 2.69
+
+@item 
+automake >= 1.14
+
+@item 
+libtool >= 2.4
+
+@item 
+autopoint >= 0.19
+
+@item 
+libltdl >= 2.4
+
+@item 
+libunistring >= 0.9.3
+
+@item 
+libcurl >= 7.26 (or libgnurl >= 7.26)
+
+@item 
+GNU libmicrohttpd >= 0.9.39
+
+@item 
+GNU libgcrypt >= 1.6
+
+@item 
+libjansson >= 2.7
+
+@item 
+Postgres >= 9.4, including libpq
+
+@item 
+libgnunetutil (from Git)
+
+@item 
+GNU Taler exchange (from Git)
+@end itemize
+
+Except for the last two, these are available in most GNU/Linux
+distributions and should just be installed using the respective package
+manager.
+
+The following sections will provide detailed instructions for installing
+the libgnunetutil and GNU Taler exchange dependencies.
+
+@node Installing libgnunetutil,Installing the GNU Taler exchange,Installation of dependencies,Generic instructions
+@anchor{taler-merchant-manual id6}@anchor{e}@anchor{taler-merchant-manual installing-libgnunetutil}@anchor{f}
+@subsection Installing libgnunetutil
+
+
+GNUnet
+Before you install libgnunetutil, you must download and install the
+dependencies mentioned in the previous section, otherwise the build may
+succeed but fail to export some of the tooling required by Taler.
+
+To download and install libgnunetutil, proceed as follows:
+
+@example
+$ git clone https://gnunet.org/git/gnunet/
+$ cd gnunet/
+$ ./bootstrap
+$ ./configure [--prefix=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, GNUnet will install to @code{/usr/local},
+which requires you to run the last step as @code{root}.
+
+@node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing libgnunetutil,Generic instructions
+@anchor{taler-merchant-manual id7}@anchor{10}@anchor{taler-merchant-manual installing-the-gnu-taler-exchange}@anchor{11}
+@subsection Installing the GNU Taler exchange
+
+
+exchange
+After installing GNUnet, you can download and install the exchange as
+follows:
+
+@example
+$ git clone git://taler.net/exchange
+$ cd exchange
+$ ./bootstrap
+$ ./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}.
+Note that you have to specify @code{--with-gnunet=/usr/local} if you
+installed GNUnet to @code{/usr/local} in the previous step.
+
+@node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions
+@anchor{taler-merchant-manual id8}@anchor{12}@anchor{taler-merchant-manual installing-the-gnu-taler-merchant-backend}@anchor{13}
+@subsection Installing the GNU Taler merchant backend
+
+
+backend
+The following steps assume all dependencies are installed.
+
+Use the following commands to download and install the merchant backend:
+
+@example
+$ git clone git://taler.net/merchant
+$ cd merchant
+$ ./bootstrap
+$ ./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
+
+Note that you have to specify @code{--with-exchange=/usr/local} and/or
+@code{--with-exchange=/usr/local} if you installed the exchange and/or
+GNUnet to @code{/usr/local} in the previous steps.
+
+@node Installing Taler on Debian GNU/Linux,,Generic instructions,Installation
+@anchor{taler-merchant-manual installing-taler-on-debian-gnu-002flinux}@anchor{14}@anchor{taler-merchant-manual installing-taler-on-debian-gnu-linux}@anchor{15}
+@section Installing Taler on Debian GNU/Linux
+
+
+Wheezy
+Debian
+Debian wheezy is too old and lacks most of the packages required.
+
+On Debian jessie, only GNU libmicrohttpd needs to be compiled from
+source. To install dependencies on Debian jesse, run the following
+commands:
+
+@example
+# apt-get install \
+  autoconf \
+  automake \
+  autopoint \
+  libtool \
+  libltdl-dev \
+  libunistring-dev \
+  libcurl4-gnutls-dev \
+  libgcrypt20-dev \
+  libjansson-dev \
+  libpq-dev \
+  postgresql-9.4
+# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz
+# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
+# gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC
+# tar xf libmicrohttpd-latest.tar.gz
+# cd libmicrohttpd-0*
+# ./configure
+# make install
+@end example
+
+For more recent versions of Debian, you should instead run:
+
+@example
+# apt-get install \
+  autoconf \
+  automake \
+  autopoint \
+  libtool \
+  libltdl-dev \
+  libunistring-dev \
+  libcurl4-gnutls-dev \
+  libgcrypt20-dev \
+  libjansson-dev \
+  libpq-dev \
+  postgresql-9.5 \
+  libmicrohttpd-dev
+@end example
+
+For the rest of the installation, follow the generic installation
+instructions starting with the installation of libgnunetutil. Note that
+if you used the Debian wheezy instructions above, you need to pass
+@code{--with-microhttpd=/usr/local/} to all @code{configure} invocations.
+
+@node How to configure the merchant’s backend,Testing,Installation,Top
+@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{16}
+@chapter How to configure the merchant’s backend
+
+
+taler-config
+taler.conf
+The installation already provides reasonable defaults for most of the
+configuration options. However, some must be provided, in particular the
+database account and bank account 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. The format of the configuration file is the well-known INI
+file format. You can edit the file by hand, or use the @code{taler-config}
+commands given as examples. For more information on @code{taler-config},
+see @ref{17,,Using taler-config}.
+
+@menu
+* Backend options:: 
+* Sample backend configuration:: 
+* Launching the backend:: 
+
+@end menu
+
+@node Backend options,Sample backend configuration,,How to configure the merchant’s backend
+@anchor{taler-merchant-manual backend-options}@anchor{18}@anchor{taler-merchant-manual id9}@anchor{19}
+@section Backend options
+
+
+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.
+
+
+@table @asis
+
+@item Service address
+
+The following option sets the transport layer address used by the
+merchant backend:
+
+UNIX domain socket
+TCP
+
+@example
+[MERCHANT]/SERVE = TCP | UNIX
+@end example
+
+If given,
+
+
+@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.
+
+port
+To run the Taler backend on TCP port 8888, use:
+
+@example
+$ taler-config -s MERCHANT -o SERVE -V TCP
+$ taler-config -s MERCHANT -o PORT -V 8888
+@end example
+
+@item Currency
+
+Which currency the Web shop deals in, i.e. “EUR” or “USD”, is
+specified using the option
+
+currency
+KUDOS
+
+@example
+[TALER]/CURRENCY
+@end example
+
+For testing purposes, the currency MUST match “KUDOS” so that tests
+will work with the Taler demonstration exchange at
+@indicateurl{https://exchange.demo.taler.net/}:
+
+@example
+$ taler-config -s TALER -o CURRENCY -V KUDOS
+@end example
+
+@item Database
+
+DBMS
+In principle is possible for the backend to support different DBMSs.
+The option
+
+@example
+[MERCHANT]/DB
+@end example
+
+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.
+
+For postgres, you need to provide:
+
+@example
+[merchantdb-postgres]/config
+@end example
+
+Postgres
+This option specifies a postgres access path using the format
+@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the
+Postgres database you want to use. Suppose @code{$USER} is the name of
+the user who will run the backend process. Then, you need to first
+run
+
+@example
+$ sudu -u postgres createuser -d $USER
+@end example
+
+as the Postgres 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.
+
+To configure the Taler backend to use this database, run:
+
+@example
+$ taler-config -s MERCHANTDB-postgres -o CONFIG \
+  -V postgres:///$DBNAME
+@end example
+
+@item Exchange
+
+exchange
+To add an exchange to the list of trusted payment service providers,
+you create a section with a name that starts with “exchange-”. In
+that section, the following options need to be configured:
+
+
+@itemize -
+
+@item 
+The “url” option specifies the exchange’s base URL. For example,
+to use the Taler demonstrator use:
+
+@example
+$ taler-config -s EXCHANGE-demo -o URL \
+  -V https://exchange.demo.taler.net/
+@end example
+
+@item 
+master key
+The “master_key” option specifies the exchange’s master public key
+in base32 encoding. For the Taler demonstrator, use:
+
+@example
+$ taler-config -s EXCHANGE-demo -o master_key \
+  -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+@end example
+
+Note that multiple exchanges can be added to the system by using
+different tokens in place of @code{demo} in the example above. Note
+that all of the exchanges must use the same currency. If you need
+to support multiple currencies, you need to configure a backend
+per currency.
+@end itemize
+
+@item Instances
+
+instance
+The backend allows the user to run multiple instances of shops with
+distinct business entities against a single backend. Each instance
+uses its own bank accounts and key for signing contracts. It is
+mandatory to configure a "default" instance.
+
+
+@itemize -
+
+@item 
+The “KEYFILE” option specifies the file containing the instance’s
+private signing key. For example, use:
+
+@example
+$ taler-config -s INSTANCE-default -o KEYFILE \
+  -V '$@{TALER_CONFIG_HOME@}/merchant/instace/default.key'
+@end example
+
+@item 
+The “NAME” option specifies a human-readable name for the
+instance. For example, use:
+
+@example
+$ taler-config -s INSTANCE-default -o NAME \
+  -V 'Kudos Inc.'
+@end example
+
+@item 
+The optional “TIP_EXCHANGE” and “TIP_EXCHANGE_PRIV_FILENAME”
+options are discussed in Tipping visitors
+@end itemize
+
+@item Accounts
+
+wire format
+In order to receive payments, the merchant backend needs to
+communicate bank account details to the exchange. For this, the
+configuration must include one or more sections named “ACCOUNT-name”
+where @code{name} can be replaced by some human-readable word
+identifying the account. For each section, the following options
+should be provided:
+
+
+@itemize -
+
+@item 
+The “URL” option specifies a @code{payto://}-URL for the account of
+the merchant. For example, use:
+
+@example
+$ taler-config -s ACCOUNT-bank -o NAME \
+  -V 'payto://x-taler-bank/bank.demo.taler.net/4'
+@end example
+
+@item 
+The “WIRE_RESPONSE” option specifies where Taler should store the
+(salted) JSON encoding of the wire account. The file given will be
+created if it does not exist. For example, use:
+
+@example
+$ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \
+  -V '@{$TALER_CONFIG_HOME@}/merchant/bank.json'
+@end example
+
+@item 
+The “PLUGIN” option specifies which wire plugin should be used for
+this account. The plugin must support the wire method used by the
+URL. For example, use:
+
+@example
+$ taler-config -s ACCOUNT-bank -o PLUGIN \
+  -V taler_bank
+@end example
+
+@item 
+For each @code{instance} that should use this account, you should set
+@code{HONOR_instance} and @code{ACTIVE_instance} to YES. The first
+option will cause the instance to accept payments to the account
+(for existing contracts), while the second will cause the backend
+to include the account as a possible option for new contracts.
+
+For example, use:
+
+@example
+$ taler-config -s ACCOUNT-bank -o HONOR_default \
+  -V YES
+$ taler-config -s ACCOUNT-bank -o ACTIVE_default \
+  -V YES
+@end example
+
+to use “account-bank” for the “default” instance.
+@end itemize
+
+Depending on which PLUGIN you configured, you may additionally
+specfiy authentication options to enable the plugin to use the
+account.
+
+For example, with @code{taler_bank} plugin, use:
+
+@example
+$ taler-config -s ACCOUNT-bank -o TALER_BANK_AUTH_METHOD \
+  -V basic
+$ taler-config -s ACCOUNT-bank -o USERNAME \
+  -V user42
+$ taler-config -s ACCOUNT-bank -o PASSWORD \
+  -V pass42
+@end example
+
+Note that additional instances can be specified using different
+tokens in the section name instead of @code{default}.
+@end table
+
+@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend
+@anchor{taler-merchant-manual id10}@anchor{1a}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{1b}
+@section Sample backend configuration
+
+
+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
+
+[INSTANCE-default]
+KEYFILE = $DATADIR/key.priv
+NAME = "Kudos Inc."
+
+[ACCOUNT-bank]
+URL = payto://x-taler-bank/bank.demo.taler.net/4
+WIRE_RESPONSE = $DATADIR/bank.json
+PLUGIN = taler_bank
+HONOR_default = YES
+ACTIVE_default = YES
+TALER_BANK_AUTH_METHOD = basic
+USERNAME = my_user
+PASSWORD = 1234pass
+
+[EXCHANGE-trusted]
+URL = https://exchange.demo.taler.net/
+MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+CURRENCY = KUDOS
+@end example
+
+Given the above configuration, the backend will use a database named
+@code{donations} within Postgres.
+
+The backend will deposit the coins it receives to the exchange at
+@indicateurl{https://exchange.demo.taler.net/}, which has the master key
+"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".
+
+Please note that @code{doc/config.sh} will walk you through all
+configuration steps, showing how to invoke @code{taler-config} for each of
+them.
+
+@node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend
+@anchor{taler-merchant-manual id11}@anchor{1c}@anchor{taler-merchant-manual launching-the-backend}@anchor{1d}
+@section Launching the backend
+
+
+backend
+taler-merchant-httpd
+Assuming you have configured everything correctly, you can launch the
+merchant backend using:
+
+@example
+$ taler-merchant-httpd
+@end example
+
+When launched for the first time, this command will print a message
+about generating your private key. If everything worked as expected, the
+command
+
+@example
+$ curl http://localhost:8888/
+@end example
+
+should return the message
+
+@example
+Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
+@end example
+
+Please note that your backend is right now likely globally reachable.
+Production systems should be configured to bind to a UNIX domain socket
+or properly restrict access to the port.
+
+@node Testing,Advanced topics,How to configure the merchant’s backend,Top
+@anchor{taler-merchant-manual id12}@anchor{1e}@anchor{taler-merchant-manual testing}@anchor{1f}
+@chapter Testing
+
+
+The tool @code{taler-merchant-generate-payments} can be used to test the
+merchant backend installation. It implements all the payment’s steps in
+a programmatically way, relying on the backend you give it as input.
+Note that this tool gets installed along all the merchant backend’s
+binaries.
+
+This tool gets configured by a config file, that must have the following
+layout:
+
+@example
+[PAYMENTS-GENERATOR]
+
+# The exchange used during the test: make sure the merchant backend
+# being tested accpets this exchange.
+# If the sysadmin wants, she can also install a local exchange
+# and test against it.
+EXCHANGE = https://exchange.demo.taler.net/
+
+# This value must indicate some URL where the backend
+# to be tested is listening; it doesn't have to be the
+# "official" one, though.
+MERCHANT = http://localbackend/
+
+# This value is used when the tool tries to withdraw coins,
+# and must match the bank used by the exchange. If the test is
+# done against the exchange at https://exchange.demo.taler.net/,
+# then this value can be "https://bank.demo.taler.net/".
+BANK = https://bank.demo.taler.net/
+
+# The merchant instance in charge of serving the payment.
+# Make sure this instance has a bank account at the same bank
+# indicated by the 'bank' option above.
+INSTANCE = default
+
+# The currency used during the test. Must match the one used
+# by merchant backend and exchange.
+CURRENCY = KUDOS
+@end example
+
+Run the test in the following way:
+
+@example
+$ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL]
+@end example
+
+The argument @code{config} given to @code{-c} points to the configuration file
+and is optional – @code{~/.config/taler.conf} will be checked by default.
+By default, the tool forks two processes: one for the merchant backend,
+and one for the exchange. The option @code{-e} (@code{-m}) avoids any exchange
+(merchant backend) fork, and just runs the generator against the
+exchange (merchant backend) running at @code{EURL} (@code{MURL}).
+
+Please NOTE that the generator contains @emph{hardcoded} values, as for
+deposit fees of the coins it uses. In order to work against the used
+exchange, those values MUST match the ones used by the exchange.
+
+The following example shows how the generator "sets" a deposit fee of
+EUR:0.01 for the 5 EURO coin.
+
+@example
+// from <merchant_repository>/src/sample/generate_payments.c
+@{ .oc = OC_PAY,
+  .label = "deposit-simple",
+  .expected_response_code = MHD_HTTP_OK,
+  .details.pay.contract_ref = "create-proposal-1",
+  .details.pay.coin_ref = "withdraw-coin-1",
+  .details.pay.amount_with_fee = concat_amount (currency, "5"),
+  .details.pay.amount_without_fee = concat_amount (currency, "4.99") @},
+@end example
+
+The logic calculates the deposit fee according to the subtraction:
+@code{amount_with_fee - amount_without_fee}.
+
+The following example shows a 5 EURO coin configuration - needed by the
+used exchange - which is compatible with the hardcoded example above.
+
+@example
+[COIN_eur_5]
+value = EUR:5
+duration_overlap = 5 minutes
+duration_withdraw = 7 days
+duration_spend = 2 years
+duration_legal = 3 years
+fee_withdraw = EUR:0.00
+fee_deposit = EUR:0.01 # important bit
+fee_refresh = EUR:0.00
+fee_refund = EUR:0.00
+rsa_keysize = 1024
+@end example
+
+If the command terminates with no errors, then the merchant backend is
+correctly installed.
+
+After this operation is done, the merchant database will have some dummy
+data in it, so it may be convenient to clean all the tables; to this
+purpose, issue the following command:
+
+@example
+$ taler-merchant-dbinit -r
+@end example
+
+@node Advanced topics,,Testing,Top
+@anchor{taler-merchant-manual advanced-topics}@anchor{20}
+@chapter Advanced topics
+
+
+@menu
+* Configuration format:: 
+* Using taler-config:: 
+* Merchant key management:: 
+* Using the SEPA wire transfer method:: 
+* Tipping visitors:: 
+* Generate payments:: 
+
+@end menu
+
+@node Configuration format,Using taler-config,,Advanced topics
+@anchor{taler-merchant-manual configuration-format}@anchor{21}
+@section Configuration format
+
+
+configuration
+In Taler realm, any component obeys to the same pattern to get
+configuration values. According to this pattern, once the component has
+been installed, the installation deploys default values in
+$@{prefix@}/share/taler/config.d/, in .conf files. In order to override
+these defaults, the user can write a custom .conf file and either pass
+it to the component at execution time, or name it taler.conf and place
+it under $HOME/.config/.
+
+A config file is a text file containing sections, and each section
+contains its values. The right format follows:
+
+@example
+[section1]
+value1 = string
+value2 = 23
+
+[section2]
+value21 = string
+value22 = /path22
+@end example
+
+Throughout any configuration file, it is possible to use @code{$}-prefixed
+variables, like @code{$VAR}, especially when they represent filesystem
+paths. It is also possible to provide defaults values for those
+variables that are unset, by using the following syntax:
+@code{$@{VAR:-default@}}. However, there are two ways a user can set
+@code{$}-prefixable variables:
+
+by defining them under a @code{[paths]} section, see example below,
+
+@example
+[paths]
+TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
+..
+[section-x]
+path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
+@end example
+
+or by setting them in the environment:
+
+@example
+$ export VAR=/x
+@end example
+
+The configuration loader will give precedence to variables set under
+@code{[path]}, though.
+
+The utility @code{taler-config}, which gets installed along with the
+exchange, serves to get and set configuration values without directly
+editing the .conf. The option @code{-f} is particularly useful to resolve
+pathnames, when they use several levels of @code{$}-expanded variables. See
+@code{taler-config --help}.
+
+Note that, in this stage of development, the file
+@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the
+component. For example, both an exchange and a bank can read values from
+it.
+
+The repository @code{git://taler.net/deployment} contains examples of
+configuration file used in our demos. See under @code{deployment/config}.
+
+@quotation
+
+@strong{Note}
+
+Expectably, some components will not work just by using default
+values, as their work is often interdependent. For example, a
+merchant needs to know an exchange URL, or a database name.
+@end quotation
+
+@node Using taler-config,Merchant key management,Configuration format,Advanced topics
+@anchor{taler-merchant-manual using-taler-002dconfig}@anchor{22}@anchor{taler-merchant-manual using-taler-config}@anchor{23}
+@section Using taler-config
+
+
+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 can also be edited by hand.
+
+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, 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 the Taler backend 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 -s ACCOUNT-bank \
+               -o WIRE_RESPONSE
+$ taler-config -f -s ACCOUNT-bank \
+               -o WIRE_RESPONSE
+@end example
+
+While the configuration file is typically located at
+@code{$HOME/.config/taler.conf}, an alternative location can be specified
+to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c}
+option.
+
+@node Merchant key management,Using the SEPA wire transfer method,Using taler-config,Advanced topics
+@anchor{taler-merchant-manual id13}@anchor{24}@anchor{taler-merchant-manual merchant-key-management}@anchor{25}
+@section Merchant key management
+
+
+merchant key
+KEYFILE
+The option “KEYFILE” in the section “INSTANCE-default” specifies the
+path to the instance’s private key. You do not need to create a key
+manually, the backend will generate it automatically if it is missing.
+While generally unnecessary, it is possible to display the corresponding
+public key using the @code{gnunet-ecc} command-line tool:
+
+@example
+$ gnunet-ecc -p                                  \
+  $(taler-config -f -s INSTANCE-default \
+                 -o KEYFILE)
+@end example
+
+@node Using the SEPA wire transfer method,Tipping visitors,Merchant key management,Advanced topics
+@anchor{taler-merchant-manual sepa-configuration}@anchor{26}@anchor{taler-merchant-manual using-the-sepa-wire-transfer-method}@anchor{27}
+@section Using the SEPA wire transfer method
+
+
+SEPA
+EBICS
+The following is a sample configuration for the SEPA wire transfer
+method: @footnote{@w{(2)} 
+Supporting SEPA is still work in progress; the backend will accept
+this configuration, but the exchange will not work with SEPA today.
+}.
+
+Then, to configure the EBICS backend for SEPA payments in EUR, the
+following configuration options need to be set:
+
+@example
+$ taler-config -s TALER -o CURRENCY -V EUR
+$ taler-config -s ACCOUNT-e -o PLUGIN -V ebics
+$ taler-config -s ACCOUNT-e -o URL \
+ -V payto://sepa/XY00111122223333444455556666
+$ taler-config -s ACCOUNT-e -o WIRE_RESPONSE
+ -V '$@{DATADIR@}/b.json'
+@end example
+
+Please note that you will also have to configure an exchange and/or
+auditors that support SEPA. However, we cannot explain how to do this
+yet as such entities do not yet exist. Once such entities do exist, we
+expect future versions of the Taler backend to ship with pre-configured
+exchanges and auditors for common denominations.
+
+@node Tipping visitors,Generate payments,Using the SEPA wire transfer method,Advanced topics
+@anchor{taler-merchant-manual id15}@anchor{28}@anchor{taler-merchant-manual tipping-visitors}@anchor{29}
+@section Tipping visitors
+
+
+tipping
+Taler can also be used to tip Web site visitors. For example, you may be
+running an online survey, and you want to reward those people that have
+dutifully completed the survey. If they have installed a Taler wallet,
+you can provide them with a tip for their deeds. This section describes
+how to setup the Taler merchant backend for tipping.
+
+There are four basic steps that must happen to tip a visitor.
+
+@menu
+* Configure a reserve and exchange for tipping:: 
+* Fund the reserve:: 
+* Authorize a tip:: 
+* Picking up of the tip:: 
+
+@end menu
+
+@node Configure a reserve and exchange for tipping,Fund the reserve,,Tipping visitors
+@anchor{taler-merchant-manual configure-a-reserve-and-exchange-for-tipping}@anchor{2a}@anchor{taler-merchant-manual id16}@anchor{2b}
+@subsection Configure a reserve and exchange for tipping
+
+
+gnunet-ecc
+reserve key
+To tip users, you first need to create a reserve. A reserve is a pool of
+money held in escrow at the Taler exchange. This is the source of the
+funds for the tips. Tipping will fail (resulting in disappointed
+visitors) if you do not have enough funds in your reserve!
+
+First, we configure the backend. You need to enable tipping for each
+instance separately, or you can use an instance only for tipping. To
+configure the “default” instance for tipping, use the following
+configuration:
+
+@example
+[INSTANCE-default]
+# this is NOT the tip.priv
+KEYFILE = signing_key.priv
+# replace the URL with the URL of the exchange you will use
+TIP_EXCHANGE = https://exchange:443/
+# here put the path to the file created with "gnunet-ecc -g1 tip.priv"
+TIP_RESERVE_PRIV_FILENAME = tip.priv
+@end example
+
+Note that the KEYFILE option should have already been present for the
+instance. It has nothing to do with the “tip.priv” file we created
+above, and you should probably use a different file here.
+
+Instead of manually editing the configuration, you could also run:
+
+@example
+$ taler-config -s INSTANCE-default \
+    -o TIP_RESERVE_PRIV_FILENAME \
+    -V tip.priv
+$ taler-config -s INSTANCE-default \
+    -o TIP_EXCHANGE \
+    -V https://exchange:443/
+@end example
+
+Next, to create the @code{TIP_RESERVE_PRIV_FILENAME} file, use:
+
+@example
+$ gnunet-ecc -g 1   \
+  $(taler-config -f -s INSTANCE-default \
+      -o TIP-RESERVE_PRIV_FILENAME)
+@end example
+
+This will create a file with the private key that will be used to
+identify the reserve. You need to do this once for each instance that is
+configured to tip.
+
+Now you can (re)start the backend with the new configuration.
+
+@node Fund the reserve,Authorize a tip,Configure a reserve and exchange for tipping,Tipping visitors
+@anchor{taler-merchant-manual fund-the-reserve}@anchor{2c}@anchor{taler-merchant-manual id17}@anchor{2d}
+@subsection Fund the reserve
+
+
+reserve
+close
+To fund the reserve, you must first extract the public key from
+“tip.priv”:
+
+@example
+$ gnunet-ecc --print-public-key \
+  $(taler-config -f -s INSTANCE-default \
+      -o TIP-RESERVE_PRIV_FILENAME)
+@end example
+
+In our example, the output for the public key is:
+
+@example
+QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
+@end example
+
+You now need to make a wire transfer to the exchange’s bank account
+using the public key as the wire transfer subject. The exchange’s bank
+account details can be found in JSON format at
+“@indicateurl{https://exchange:443//wire/METHOD}” where METHOD is the respective wire
+method (i.e. “sepa”). Depending on the exchange’s operator, you may also
+be able to find the bank details in a human-readable format on the main
+page of the exchange.
+
+Make your wire transfer and (optionally) check at
+“@indicateurl{https://exchange:443/reserve/status/reserve_pub=QPE24X}...” whether your
+transfer has arrived at the exchange.
+
+Once the funds have arrived, you can start to use the reserve for
+tipping.
+
+Note that an exchange will typically close a reserve after four weeks,
+wiring all remaining funds back to the sender’s account. Thus, you
+should plan to wire funds corresponding to a campaign of about two weeks
+to the exchange initially. If your campaign runs longer, you should wire
+further funds to the reserve every other week to prevent it from
+expiring.
+
+@node Authorize a tip,Picking up of the tip,Fund the reserve,Tipping visitors
+@anchor{taler-merchant-manual authorize-a-tip}@anchor{2e}@anchor{taler-merchant-manual id18}@anchor{2f}
+@subsection Authorize a tip
+
+
+When your frontend has reached the point where a client is supposed to
+receive a tip, it needs to first authorize the tip. For this, the
+frontend must use the “/tip-authorize” API of the backend. To authorize
+a tip, the frontend has to provide the following information in the body
+of the POST request:
+
+
+@itemize -
+
+@item 
+The amount of the tip
+
+@item 
+The justification (only used internally for the back-office)
+
+@item 
+The URL where the wallet should navigate next after the tip was
+processed
+
+@item 
+The tip-pickup URL (see next section)
+@end itemize
+
+In response to this request, the backend will return a tip token, an
+expiration time and the exchange URL. The expiration time will indicate
+how long the tip is valid (when the reserve expires). The tip token is
+an opaque string that contains all the information needed by the wallet
+to process the tip. The frontend must send this tip token to the browser
+in a special “402 Payment Required” response inside the @code{X-Taler-Tip}
+header.
+
+The frontend should handle errors returned by the backend, such as
+missconfigured instances or a lack of remaining funds for tipping.
+
+@node Picking up of the tip,,Authorize a tip,Tipping visitors
+@anchor{taler-merchant-manual id19}@anchor{30}@anchor{taler-merchant-manual picking-up-of-the-tip}@anchor{31}
+@subsection Picking up of the tip
+
+
+The wallet will POST a JSON object to the shop’s “/tip-pickup” handler.
+The frontend must then forward this request to the backend. The response
+generated by the backend can then be forwarded directly to the wallet.
+
+@node Generate payments,,Tipping visitors,Advanced topics
+@anchor{taler-merchant-manual generate-payments}@anchor{32}@anchor{taler-merchant-manual id20}@anchor{33}
+@section Generate payments
+
+
+testing database
+The merchant codebase offers the @code{taler-merchant-benchmark} tool to
+populate the database with fake payments. This tool is in charge of
+starting a merchant, exchange, and bank processes, and provide them all
+the input to accomplish payments. Note that each component will use its
+own configuration (as they would do in production).
+
+The tool takes all of the values it needs from the command line, with
+some of them being mandatory. Among those, we have:
+
+
+@itemize -
+
+@item 
+@code{--currency=K} Use currency @emph{K}, for example to craft coins to
+withdraw.
+
+@item 
+@code{--bank-url=URL} Assume that the bank is serving under the base URL
+@emph{URL}. This option is only actually used by the tool to check if the
+bank was well launched.
+
+@item 
+@code{--merchant-url=URL} Reach the merchant through @emph{URL}, for
+downloading contracts and sending payments.
+@end itemize
+
+The tool then comes with two operation modes: @emph{ordinary}, and @emph{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 abilty of driving the aggregation policy is useful for testing
+the backoffice 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 @emph{corner} mode. Among the most
+interesting, there are:
+
+
+@itemize -
+
+@item 
+@code{--two-coins=TC} This option instructs the tool to perform @emph{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 @emph{UN} (one coin) payments that will be left unaggregated.
+
+@item 
+@code{--alt-instance=AI} This option instructs the tool to perform
+payments using the merchant instance @emph{AI} (instead of the @emph{default}
+instance)
+@end itemize
+
+As for the @code{ordinary} subcommand, it is worth explaining the following
+options:
+
+
+@itemize -
+
+@item 
+@code{--payments-number=PN} Instructs the tool to perform @emph{PN} payments.
+
+@item 
+@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking
+operations. Note that the @strong{total} amount of operations will be two
+times @emph{TN}, since "one" tracking operation accounts for
+@code{/track/transaction} and @code{/track/transfer}. This command should
+only be used to see if the operation ends without problems, as no
+actual measurement of performance is provided (despite of the
+’benchmark’ work used in the tool’s name).
+@end itemize
+@anchor{17}@w{                              }
+@anchor{taler-merchant-manual Using-taler_002dconfig}@w{                              }
+
+@c %**end of body
+@bye