path: root/doc/manual.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename manual.info
@include version-manual.texi
@settitle The GNU Taler merchant backend operator tutorial @value{VERSION}

@include syntax.texi

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying
This manual is for the GNU Taler merchant backend (version @value{VERSION}, @value{UPDATED}),

Copyright @copyright{} 2016, 2017 Taler Systems SA

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@c If your manual is published on paper by the FSF, it should include
@c The standard FSF Front-Cover and Back-Cover Texts, as given in
@c maintain.texi.
@c
@c Titlepage
@c
@titlepage
@title The GNU Taler merchant backend operator tutorial
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
@author Christian Grothoff (@email{christian.grothoff@@inria.fr})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents
@contents

@ifnottex
@node Top
@top The GNU Taler manual for Web shops
@insertcopying
@end ifnottex

@menu
* Introduction::            Whom this manual is addressed to
* Installation::            Installing the Merchant backend
* Configuration::           How to set up the Merchant backend
* Testing::                 How to test the installed Merchant backend
* Advanced topics::         Detailed solutions to specific issues


Appendices

* GNU-LGPL::                     The GNU Lesser General Public License says how you
                                 can use the code of libtalermerchant.so in your own projects.
* GNU Affero GPL::               The Affero GNU General Public License says how you
                                 can copy and share the Taler merchant backend.
* GNU-FDL::                      The GNU Free Documentation License says how you
                                 can copy and share the documentation of GNU Taler.

Indices

* Concept Index::               Index of concepts and programs.

@end menu


@node Introduction
@chapter Introduction

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

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

@c The fouth chapter will explain how to test that the setup worked correctly.

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.

@section Architecture overview

@cindex crypto-currency
@cindex 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
@cindex frontend
@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. This manual
  describes how to integrate Taler with Web shop frontends.
@cindex back office
@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
  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.
@cindex backend
@item 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.
@cindex DBMS
@cindex Postgres
@item 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:

@center @image{arch, 3in}

@cindex 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
@menu
* Installing Taler using Docker:: Installing Taler using Docker
* generic-instructions:: Generic installation guidelines
* Installing Taler on Debian GNU/Linux:: Installing Taler on Debian GNU/Linux
@c * Installing Taler with GNU Guix:: Installing Taler with GNU Guix
@c * Installing Taler on Arch Linux:: Installing Taler on Arch Linux
@c * Installing Taler on Windows:: Installing Taler on Windows
@c * Installing Taler on OS X:: Installing Taler on OS X
@end menu

@chapter Installation

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

@node Installing Taler using Docker
@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{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:

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

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

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

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

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

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:

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


@node generic-instructions
@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.

@subsection Installation of dependencies

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

@itemize
@item autoconf @math{\ge 2.69}
@item automake @math{\ge 1.14}
@item libtool @math{\ge 2.4}
@item autopoint @math{\ge 0.19}
@item libltdl @math{\ge 2.4}
@item libunistring @math{\ge 0.9.3}
@item libcurl @math{\ge 7.26} (or libgnurl @math{\ge 7.26})
@item GNU libmicrohttpd @math{\ge 0.9.39}
@item GNU libgcrypt @math{\ge 1.6}
@item libjansson @math{\ge 2.7}
@item Postgres @math{\ge 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.


@subsection Installing libgnunetutil

@cindex 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}.

@subsection Installing the GNU Taler exchange

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


@subsection Installing the GNU Taler merchant backend

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

@c @node Installing Taler with GNU Guix
@c @section Installing Taler with GNU Guix

@c This section has not yet been written.




@node Installing Taler on Debian GNU/Linux
@section Installing Taler on Debian GNU/Linux

@cindex Wheezy
@cindex 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.



@c @node Installing Taler on Arch Linux
@c @section Installing Taler on Arch Linux

@c This section has not yet been written.


@c @node Installing Taler on Windows
@c @section Installing Taler on Windows

@c This section has not yet been written.


@c @node Installing Taler on OS X
@c @section Installing Taler on OS X

@c This section has not yet been written.


@node Configuration
@chapter How to configure the merchant's backend

@cindex taler-config
@cindex 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}, @pxref{Using taler-config}.


@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:

@cindex UNIX domain socket
@cindex 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.

@c FIXME: we should offer an option to bind the TCP socket to a particular IP address (#4752)

@cindex 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

@cindex currency
@cindex 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 @url{https://exchange.demo.taler.net/}:

@example
$ taler-config -s TALER -o CURRENCY -V KUDOS
@end example


@item Database
@cindex 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
@cindex 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
@cindex 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
@cindex 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

@c FIXME: In the future, we need to describe specifying auditors here.
@c @item Auditors


@item Instances
@cindex 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 @cite{Tipping visitors}
@end itemize



@item Accounts
@cindex 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



@c Document EBICS here once supported.

Note that additional instances can be specified using different tokens
in the section name instead of @code{default}.

@end table


@section Sample backend configuration

@cindex configuration
The following is an example for a complete backend configuration:

@smallexample
[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 smallexample


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
@url{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.

@section Launching the backend

@cindex backend
@cindex 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

@smallexample
Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
@end smallexample

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
@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
@c FIXME: the last option should be removed and [taler]/CURRENCY used instead!

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
@chapter Advanced topics

@menu
* Configuration in Taler::  Configuration patterns
* Using taler-config::      Introduction to the taler-config tool
* Key management::          Managing the merchant's cryptographic keys
* SEPA configuration::      Configuring a SEPA bank account
* Tipping visitors::        Giving money to Web site visitors with Taler
@end menu

@node Configuration in Taler
@section Configuration in Taler
@cindex 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 @cite{$@{prefix@}/share/taler/config.d/}, in
@cite{.conf} files.  In order to override these defaults, the user can write a custom
@cite{.conf} file and either pass it to the component at execution time, or name it
@cite{taler.conf} and place it under @cite{$HOME/.config/}.


A config file is a text file containing @cite{sections}, and each section contains
its @cite{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 @cite{.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}.

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


@node Using taler-config
@section Using taler-config
@cindex 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 Key management
@section Merchant key management
@cindex merchant key
@cindex 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

@c Add more on how to add that key to X.509 CSRs once we can do that.

@node SEPA configuration
@section Using the SEPA wire transfer method
@cindex SEPA
@cindex EBICS

The following is a sample configuration for the SEPA wire transfer
method:@footnote{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
@section Tipping visitors
@cindex 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.

@subsection Configure a reserve and exchange for tipping
@cindex gnunet-ecc
@cindex reserve key

@c TODO: We should probably create a tool that automates the
@c configuration process and simply outputs the wire transfer
@c subject of the reserve.

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.


@subsection Fund the reserve
@cindex reserve
@cindex 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
``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
``https://exchange:443/reserve/status/reserve_pub=QPE24X...''
whether your transfer has arrived at the exchange.
@c FIXME: we should create a nicer tool to do this check!

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.


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


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


@c **********************************************************
@c *******************  Appendices  *************************
@c **********************************************************

@node GNU-LGPL
@unnumbered GNU-LGPL
@cindex license
@cindex LGPL
@include lgpl.texi

@node GNU Affero GPL
@unnumbered GNU Affero GPL
@cindex license
@cindex Affero GPL
@include agpl.texi

@node GNU-FDL
@unnumbered GNU-FDL
@cindex license
@cindex GNU Free Documentation License
@include fdl-1.3.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye