\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@@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 * Hello-world:: How to set up a minimalistic shop * Back-office-integration:: How to integrate with the back office * Advanced topics:: Detailed solutions to specific issues @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). @section About this manual This manual addresses how to integrate GNU Taler with Web shops. It describes how to install a GNU Taler merchant @emph{backend} and how to integrate it with an existing Web shop @emph{frontend}. The manual is for system administrators and Web developers. We expect some moderate familiarity with the compilation and installation of free software packages and of Web technology, in particular HTML and HTTP. An understanding of cryptography is not required. You can download all of the code examples given in this tutorial from @url{https://git.taler.net/merchant.git/tree/doc/examples/}. @section Architecture overview The Taler software stack for a merchant consists of four main components: @itemize @item A frontend which interacts with the customer's browser. The frontend enables the customer to build a shopping cart and place an order. Upon payment, it triggers the respective business logic to satisfy the order. This component is not included with Taler, but rather assumed to exist at the merchant. This manual describes how to integrate Taler with Web shop frontends. @item A back office application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied. This component is 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 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 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, 4in} 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 * 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 using Docker:: Installing Taler using Docker @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 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.37} @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 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-' 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. @c @node Installing Taler with GNU Guix @c @section Installing Taler with GNU Guix @c This section has not yet been written. @c @node Installing Taler using Docker @c @section Installing Taler using Docker @c This section has not yet been written. @node Installing Taler on Debian GNU/Linux @section Installing Taler on Debian GNU/Linux 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 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: @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) 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 @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/}: @example $ taler-config -s merchant -o currency -V KUDOS @end example @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. 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 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 $ createuser -d $USER @end example as the @code{postgres} database administrator 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 To add an exchange to the list of trusted payment service providers, you create a section with a name that starts with ``merchant-exchange-''. In that section, the following options need to be configured: @itemize @item The ``uri'' option specifies the exchange's base URL. For example, to use the Taler demonstrator use: @example $ taler-config -s merchant-exchange-demo -o config \ -V https://exchange.demo.taler.net/ @end example @item The ``master_key'' option specifies the exchange's master public key in base32 encoding. For the Taler demonstrator, use: @example $ taler-config -s merchant-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 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/}: @example $ taler-config -s merchant -o wireformat -V test @end example 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: @itemize @item The option ``keyfile'' in the section ``merchant-instance-default'' 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/or to display the existing public key using the @code{gnunet-ecc} command-line tool: @example $ gnunet-ecc -p \ `taler-config -f -s merchant-instance-default \ -o keyfile` @end example @item The option ``test_response_file'' in the section ``merchant-instance-wireformat-default'' 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 These bank details are included in the contract in their hashed form. Hence, the random @code{salt} is necessary to make it difficult for customers to invert the hash by brute-force. You should substitute the account number with your actual account number. In order to get an account number, register at our demonstration bank at @url{https://bank.demo.taler.net/} using your browser. Assuming this JSON specification is stored in a file @code{$TEST.json}, run: @example $ taler-config -s merchant-instance-wireformat-default \ -o test_response_file -v $TEST.json @end example Note that additional instances can be specified using different tokens in the section name instead of @code{default}. @end itemize @end table @section Sample backend configuration The following is an example for a complete backend configuration: @smallexample [merchant] wireformat = TEST serve = TCP port = 8888 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 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". 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 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: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 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: @smallexample
@end smallexample When the server-side handler for @code{/donate} receives the form submission, it will return a HTML page that will take care of: @itemize @item showing a credit card paywall to the user if no wallet is found, and @item fetching a Taler contract and passing it to the wallet if one is found @end itemize A minimalistic @code{/donate} handler is shown below (in PHP): @smallexample // donate_handler.php @include examples/donate_handler.php @end smallexample Given this response, the Taler wallet will fetch the contract from @url{/generate-contract} and display it to the user. If the wallet is not present, the HTML body will be shown and the Taler headers will be ignored by the browser. Instead of specifying the contract via an URL, it is also possible to inline short contracts directly. Note that we @emph{could} have bypassed the POST request to trigger the payment, and performed the interaction with the wallet directly from the button via JavaScript. @c We will consider this case in a later chapter. @c FIXME: not yet ;-) @section Generating the contract The server-side handler for @code{/generate-contract} now has to generate a contract proposal about donating 1 KUDOS to the 'Taler charity program'. This proposed contract is then POSTed to the backend at @code{/contract}. The main result of POSTing the proposal to the backend is that it will be cryptographically signed. This is necessary as by design the frontend does not perform any cryptographic work. A simple @code{/generate-contract} handler may thus look like this: @smallexample // generate_contract.php @include examples/generate_contract.php @end smallexample Note that in practice the frontend might want to generate a monotonically increasing series of transaction IDs to avoid a chance of collisions. Transaction IDs must be in the range of @math{[0:2^{51})}. The function @code{post_to_backend} is shown below; we will use it again in other examples: @smallexample // post_to_backend.php @include examples/post_to_backend.php @end smallexample After the browser has fetched the contract, the user will be given the opportunity to affirm the payment. @section Receiving payments via Taler The next step for the frontend is to accept the payment from the wallet, assuming the user accepts the contract. For this, the frontend must implement a payment handler at the URI specified for as the @code{X-Taler-Pay-Url} in the example above. The role of the @code{/pay} handler is to receive the payment from the wallet and forward it to the backend. If the backend reports that the payment was successful, the handler needs to update the session state with the browser to remember that the user paid. The following code implements this in PHP: @smallexample // pay_handler.php @include examples/pay_handler.php @end smallexample Do not be confused by the @code{isset} test for the session state. In our simple example, it will be set to ``false'' by the fulfillment URL which the browser actually always visits first.@footnote{This is for technical reasons; the natural logical progression would of course be to pay before accessing the fulfillment URL.} We describe how the fulfillment URL works in the next section. @section The fulfillment page The fulfillment page can be called by users that have already paid for the item, as well as by users that have not yet paid at all. The fulfillment page must use the HTTP session state to detect if the payment has been performed already, and if not request payment from the wallet. For our example, we include in the URI of the fulfillment page the data which is needed to allow the page to determine which contract the user is trying to access. Thus, the fulfillment URL for our example looks like the following:@* @smallexample https://shop.com/fulfillment? \ transaction_id=×tamp= @end smallexample @*The @code{/fulfillment} handler will then perform the following actions: @smallexample // fulfillment_handler.php @include examples/fulfillment_handler.php @end smallexample @node Back-office-integration @chapter Integration of GNU Taler with the back office @node Advanced topics @chapter Advanced topics @menu * Using taler-config:: Introduction to the taler-config tool @end menu @node Using taler-config @section Using taler-config The tool @code{taler-config} can be used to extract or manipulate configuration values; however, the configuration use the well-known INI file format and 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 merchant-instance-wireformat-default \ -o test_response_file $ taler-config -f -s merchant-instance-wireformat-default \ -o test_response_file @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. @bye @node Advanced-topics @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".