\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename manual.info
@include version.texi
@settitle The GNU Taler manual for Web shop operators @value{VERSION}
@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 INRIA
@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 manual for Web shops
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
@author Christian Grothoff (@email{christian.grothoff.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
* Hello-world:: How to set up a minimalistic shop
@end menu
@node Introduction
@chapter Introduction
This manual addresses how to integrate GNU Taler with Web shops. It
describes how to install a GNU Taler merchant @emph{backend} and make it
communicate with an existing Web shop @emph{frontend}.
@c FIXME: add summary of what the reader will learn.
In detail, the manual shows how to install all the required dependencies
of the backend and how to tune its configuration to serve your shop.
We conclude the initial part with a tutorial about a minimalistic frontend
having a donation button which uses Taler payments.
@c FIXME: explain target audience (system administrators and frontend Web developers)
This manual is mainly addressed to system administrators, as the backend is
a @emph{service}, and Web developers, as their sites need to interact with the
backend.
@section Architecture overview
The backend provides the cryptographic support, stores Taler-specific
financial information in a DBMS and communicates with the GNU Taler
exchange. 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 (such as the
merchant's signing keys and bank account information).
@center @image{arch, 3in, 4in}
@c FIXME: How?
@c and possibly even back office (Web service for shop owner)
@c and interactions (select products, pay, deposit, confirm, persist, track)
@node Installation
@menu
* generic-instructions:: Generic installation guidelines
* dependencies:: List all needed dependencies to install the backend
* Installing Taler with GNU Guix:: Installing Taler with GNU Guix
* Installing Taler using Docker:: Installing Taler using Docker
* Installing Taler on Debian GNU/Linux:: Installing Taler on Debian GNU/Linux
* Installing Taler on Arch Linux:: Installing Taler on Arch Linux
* Installing Taler on Windows:: Installing Taler on Windows
* 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 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.
@node dependencies
@section Dependencies
@subsection Installation of dependencies
The following packages need to be installed before we can compile the
backend:
@itemize
@item libcurl or libgnurl
@item GNU libmicrohttpd, including GnuTLS
@item GNU libgcrypt
@item libjansson
@item Postgres, including libpq
@item GNUnet
@item GNU Taler exchange
@end itemize
The first five are available in most GNU/Linux distributions and should
just be installed using the respective package manager, for example
using
@example
# apt-get install libcurl4-gnutls-dev \
libmicrohttpd-dev \
libgnutls-dev \
libgcrypt20-dev \
libjansson-dev \
libpq-dev \
postgresql-9.5
@end example
The following sections will provide detailed instructions for
installing the GNUnet and GNU Taler exchange dependencies.
@subsection Installing GNUnet
Note that a Web shop supporting GNU Taler does not actually need to run a
GNUnet peer. The requirement to have a minimal GNUnet installation
arises from the fact that GNUnet provides some required routines for
doing cryptography, string manupulation, interfacing with databases,
JSON manipulation, logging and operating system abstractions. Hence
this manual does not describe how to actually run a GNUnet peer, and
we also skip optional GNUnet dependencies that an ordinary peer might
want to include in the installation. Thus, do not be alarmed if the
GNUnet build process warns you about missing (optional) dependencies.
Before you install GNUnet, you should download and install the
dependencies mentioned in the previous section, otherwise GNUnet may
install but fail to export some of the tooling required by Taler.
To download and install GNUnet, proceed as follows:
@example
$ svn checkout https://gnunet.org/svn/gnunet/
$ cd gnunet/
$ ./bootstrap
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-' 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
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-' 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
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-' 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 with GNU Guix
@section Installing Taler with GNU Guix
This section has not yet been written.
@node Installing Taler using Docker
@section Installing Taler using Docker
This section has not yet been written.
@node Installing Taler on Debian GNU/Linux
@section Installing Taler on Debian GNU/Linux
This section has not yet been written.
@node Installing Taler on Arch Linux
@section Installing Taler on Arch Linux
This section has not yet been written.
@node Installing Taler on Windows
@section Installing Taler on Windows
This section has not yet been written.
@node Installing Taler on OS X
@section Installing Taler on OS X
This section has not yet been written.
@node Configuration
@chapter How to configure the merchant's backend
The installation already provides reasonable defaults for most of the
configuration options. However, some of them must be tuned to the
particular Web shop. 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 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:
@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)
@item Currency
Which currency the Web shop deals in, i.e. ``EUR'' or ``USD'', is specified using the option
@example
[merchant]/currency
@end example
For testing purposes, the currency should match ``KUDOS'' which is used by the Taler
demonstration exchange at @url{https://exchange.demo.taler.net/}.
@item Database
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.
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
This option specifies a postgres access path using the format
"postgres:///DBNAME", where DBNAME is the name of the Postgres
database you want to use. Suppose USER is the name of the
user who will run the backend process. Then, you need to first run
@example
$ createuser -d USER
@end example
as the @code{postgres} database administrator to grant USER
the ability to create new databases. Next, you should as
USER run
@example
$ createdb DBNAME
@end example
to create the backend's database. Here, DBNAME must match the database name
given in the configuration file.
@item 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-''
and set the following options in that section:
@example
[merchant-exchange-MYEXCHANGE]/uri
@end example
Takes the exchanges base URL, e.g. @url{https://exchange.demo.taler.net/}.
@example
[merchant-exchange-MYEXCHANGE]/master_key
@end example
Takes the base32 encoding of the exchange's master public key,
e.g.
@example
CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00.
@end example
Note that multiple exchanges can be added to the system by using different
tokens in place of @code{MYEXCHANGE} in the example above.
@c FIXME: In the future, we need to describe specifying auditors here.
@item Wireformat
In order to receive payments, the merchant backend needs to communicate bank
account details to the exchange. The banking system used is specified using the
following global option:
@example
[merchant]/wireformat
@end example
The value @code{test} can be used to interact with the Taler
demonstrator at @url{https://bank.demo.taler.net/}. Other wireformats
will be supported in the future to interact with actual banks.
@item Instances
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 account and key for signing contracts. It is
mandatory to configure a "default" instance using the following
options:
@example
[merchant-instance-default]/keyfile
@end example
Specifies the path to the instance's private key. You do not need to
create a key at this time, the backend will generate it automatically
if it is missing. While generally unnecessary, it is possible to
generate the key and to display the public key using the
@code{gnunet-ecc} command-line tool.
@example
[merchant-instance-wireformat-default]/test_response_file
@end example
This option specifies the path to a file that describes the instance's
wire details in JSON format. The specific format depends slightly
on the banking system selected via the @code{wireformat} option.
For the @code{test} wire format, a sample specification looks as follows:
@verbatim
{
"type": "test",
"bank_uri": "https://bank.test.taler.net/",
"account_number": 5,
"salt": "RANDOMSALT"
}
@end verbatim
Those bank details above, are included in the contract in their hashed
form, so the 'salt' field is needed to make harder brute-forcing them.
In order to get an account number, register at our demonstration bank:
@url{https://bank.demo.taler.net/}
Note that additional instances can be specified using different tokens
in the section name instead of @code{default}.
@end table
@section Sample backend configuration
The following is an example for a complete backend configuration:
@example
[merchant]
wireformat = TEST
serve = TCP
port = 9898
currency = EUR
database = postgres
[merchant-instance-default]
KEYFILE = $DATADIR/key.priv
[merchant-instance-wireformat-default]
TEST_RESPONSE_FILE = $DATADIR/test.json
[merchantdb-postgres]
config = postgres:///donations
[merchant-demoexchange]
uri = https://exchange.demo.taler.net/
master_key = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
@end example
The configuration file is typically located at
@code{$HOME/.config/taler.conf}. An alternative location can be
specified to @code{taler-merchant-httpd} using the @code{-c} option.
The contents of @code{$DATADIR/test.json} might look like this:
@example
@{
"type": "test",
"bank_uri": "https://bank.example.com/",
"account_number": 15,
"salt": "1851695201"
@}
@end example
The resulting backend will be listening on port 9898.
The backend's private key will be located at @code{$DATADIR/key.priv}.
You can determine the expaned path using
@smallexample
$ taler-config -f -s merchant-instance-wireformat-default -o TEST_RESPONSE_FILE
@end smallexample
The backend will use a database named @code{donations} within
Postgresql.
The backend will deposit the coins it receives to the exchange at
@url{https://exchange.demo.taler.net/}, which has the master key @*
"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".
@section Launching the backend
As mentioned previously, the system adminstrator should make sure that
a database named @code{donations} is defined and accessible in the
system. Once this configuration is ready, the
merchant backend can be launched using:
@example
$ taler-merchant-httpd
@end example
If everything worked as expected, the command
@example
$ curl http://localhost:9898/
@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 Hello-world
@chapter Setting up a simple Web shop with GNU Taler
This section describes how to setup a simple shop, which exposes a
button to get donations via Taler. The expected behaviour is that once
the ``donate'' button is clicked, the customer will receive a Taler
contract offering him the opportunity to make a fixed donation,
for example to donate 1 KUDOS to the charity operating the shop.
Note that if the customer does not have the Taler wallet installed,
they should instead be prompted to proceed with a classic dialog for
credit card payments.
@section Prompting for payment
Our goal is to trigger a Taler payment once the customer has clicked
on a donation button. We will use a button that issues an HTTP POST
to the frontend @code{/donate} URL. For this, the HTML would be as
follows:
@example
";
return;
@}
else@{
echo '';
return;
@}
@}
# Reconstruct the contract
$rec_proposal = make_contract($_GET['transaction_id'], $_GET['timestamp']);
# $response obeys to the specification at:
# https://api.taler.net/api-merchant.html#offer
$response = post_to_backend("/contract", $rec_proposal);
http_response_code (402);
header ('X-Taler-Contract-Hash: json_decode($response)["H_contract"]');
header ('X-Taler-Offer-Url: /donate');
header ('X-Taler-Pay-Url: /pay'); ?>
@end smallexample
@chapter Advanced topics
This chapter includes draft texts for advanced topics which have
not yet been properly integrated with the main text.
@section Using the SEPA wire transfer method
Let's say that all the donations go to the following recipient,
expressed in @code{SEPA} format@footnote{As said, supporting SEPA is still
work in progress}.
@verbatim
{
"type": "SEPA",
"IBAN": "XY00 1111 2222 3333 4444 5555 6666",
"name": "Taler charity program",
"BIC": "XXXXAB99",
"salt": "RANDOMSALT"
}
@end verbatim
Assume this information is stored in file @code{$DATADIR/sepa.json}.
@section Payments using JavaScript
The function @code{executePayment} exported by @code{taler-wallet-lib.js} will basically
hand its three parameters to the wallet which implements the following semantics:@*
check in the internal DB if @code{$response['H_contract']} has an entry, and:
@itemize
@item if that is the case, then the user accepted the contract previously and the wallet
sends a deposit permission @footnote{Roughly speaking, a deposit permission is a JSON
containing the coins to pay for a contract. Its full specification is available at:
@url{https://api.taler.net/api-merchant.html#depositpermission}} to @code{/frontend-pay}.
If this operation succeeds, then visit again the fulfillment URL, and finally enjoy
the product.
@item if not, redirect the browser to @code{/donate} (which will then reinitiate the
whole contract negotiation). This happens when the user visits a shared fulfillment URL.
The idea is to let that user buy the same products as the user who shared the fulfillment
URL. Nonetheless, the shop is not forced to follow this semantics when provides the third
parameter to @code{executePayment}.
@end itemize
@section Design considerations for the fulfillment page
The fulfillment page mechanism is designed to provide the following two properties:
@enumerate
@item Taler payments @emph{can} be implemented in DB-less frontends.
@item Taler payments are replayable, meaning that each purchase is associated with
a URL (the fulfillment URL) that shows the product each time it gets visited (and
of course, only the first time takes the user's money).
@end enumerate
In order to implement property (1), the frontend needs a way to recall
what a contract is about (e.g. which product, which price, the
timestamp, etc.) before proceeding with the actual payment and
eventually deliver the final product. That is achieved by
@emph{reconstructing} the contract using the fulfillment page's URL
parameters@footnote{the fulfillment URL equipped with all the
parameters is included in the contract}.
In order to implement property (2), the frontend will firstly check
the state to see if the product claimed among the fulfillment URL
parameter has been paid; if so, the product is given to the
customer. Otherwise, the frontend sets the payment as "pending" in the
state and @emph{executes} it in the wallet. The payment execution is
performed by returning JavaScript code from @code{taler-wallet-lib.js}
that triggers the wallet to send the payment to the pay page. Once
the pay page receives the payment, it sets the state for the payment
as "payed".
@bye