summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-06-26 17:42:30 +0200
committerChristian Grothoff <christian@grothoff.org>2020-06-26 17:42:30 +0200
commit18012a7d0568cda761b6f7886fa445e4e8f8ff65 (patch)
tree09da500abf890c22d58f0a63a6a788a16a8f3c14
parent704a5e1eceed1a6f73d7998ce3068e848ac03e87 (diff)
downloaddocs-18012a7d0568cda761b6f7886fa445e4e8f8ff65.tar.gz
docs-18012a7d0568cda761b6f7886fa445e4e8f8ff65.tar.bz2
docs-18012a7d0568cda761b6f7886fa445e4e8f8ff65.zip
terminology for merchant backend
-rw-r--r--taler-merchant-api-tutorial.rst23
-rw-r--r--taler-merchant-manual.rst289
2 files changed, 247 insertions, 65 deletions
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index 6442e7c2..eb9505ce 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -1,5 +1,26 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2020 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+ @author Florian Dold
+ @author Christian Grothoff
+
+.. _merchant-api-tutorial:
+
GNU Taler Merchant API Tutorial
-###################################
+###############################
Introduction
============
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 7e3eac6d..6ffd193d 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -73,21 +73,24 @@ components:
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.
+ assumed to exist at the merchant.
+ The `Merchant API Tutorial <#merchant-api-tutorial>`__ gives an
+ introduction for how to integrate Taler with Web shop frontends.
- 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.
+ not included with Taler, but rather assumed to exist at the
+ merchant. The `Merchant Backend API <#merchant-api>`__ provides
+ the API specification that should be reviewed to integrate such a
+ back office with the Taler 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.
+ to process financial transactions with Taler. This manual primarily
+ describes how to install and configure this backend.
- 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.
+ DBMS. Please review the Postgres documentation for details on
+ how to configure the database.
The following image illustrates the various interactions of these key
components:
@@ -96,13 +99,150 @@ components:
.. index:: 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.
+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.
+
+A typical deployment will additionally include a full-blown Web server (like
+Apache or Nginx). Such a Web server would be responsible for TLS termination
+and access control to the /private/ API endpoints of the merchant backend.
+Please carefully review the section on `Secure setup <#Secure-setup>`__ before
+deploying a Taler merchant backend to production.
+
+
+Terminology
+===========
+
+This chapter describes some of the key concepts used throughout the manual.
+
+Instances
+---------
+
+.. index:: instance
+
+The backend allows the user to run multiple *instances* of shops with distinct
+business entities sharing a single backend. Each instance uses its own bank
+accounts and key for signing contracts. All major accounting functionality is
+separate per instance. What is shared is the database, HTTP(S) address and
+the main Taler configuration (accepted currency, exchanges and auditors).
+
+Accounts
+--------
+
+.. index:: account
+
+To receive payments, an instance must have configured one or more bank
+*accounts*. The backend does not have accounts for users, and instances are
+also not really 'accounts'. So whenever we use the term *account*, it is about
+a bank account of a merchant.
+
+Inventory
+---------
+
+.. index:: inventory
+.. index:: product
+.. index:: lock
+.. index:: unit
+.. index:: order
+
+The Taler backend offers inventory management as an optional function.
+Inventory is tracked per instance and consists of *products* sold in
+*units*. Inventory can be finite or infinite (for digital products).
+Products may include previews (images) to be shown to the user and other
+meta-data. Inventory management allows the frontend to *lock* products,
+reserving them for a particular (unpaid) *order*. The backend can keep
+track of how many units of a product remain in stock and ensure that
+the number of units sold does not exceed the number of units in stock.
+
+Inventory management is optional, and it is possible for the frontend to
+include products in orders that are not in the inventory, or to override
+prices of products in the inventory.
+
+Orders and Contracts
+--------------------
+
+.. index:: order
+.. index:: contract
+.. index:: claim
+.. index:: pay
+.. index:: refund
+.. index:: wire deadline
+.. index:: lock
+.. index:: legal expiration
+
+In Taler, users pay merchants for orders. An order is first created by the
+merchant, where the merchant specifies the specific terms of the order.
+
+After an order is created, it is *claimed* by a wallet. Once an order is
+claimed by a specific wallet, only that wallet will be able to pay for this
+order, to the exclusion of other wallets even if they see the same order URL.
+
+A wallet may *pay* for a claimed order, at which point the order turns into
+a (paid) contract. Orders have an expiration date after which the commercial
+offer expires and any stock of products *locked* by the order is released,
+allowing the stock to be sold in other orders.
+
+Once a contract has been paid, the merchant should fulfill the contract. It
+is possible for the merchant to *refund* a contract order, for example if the
+contract cannot be fulfilled after all. Refunds are only possible until the
+exchange has *wired* the payment to the merchant. Once the funds have been
+wired, refunds are no longer allowed by the Taler exchange. The *wire
+deadline* specifies the latest time by which an exchange must wire the funds,
+while the (earlier) *refund deadline* specifies the earliest time when an
+exchange may wire the funds.
+
+Contract information is kept for legal reasons, typically to provide tax
+records in case of a tax audit. After the *legal expiration* (by default a
+decade), contract information is deleted.
+
+Transfers
+---------
+
+.. index:: transfer
+.. index:: wire transfer
+
+The Taler backend can be used to verify that the exchange correctly wired all
+of the funds to the merchant. However, the backend does not have access to the
+incoming wire transfers of the merchant's bank account. Thus, merchants must
+manually provide the backend with wire *transfer* data that specifies the wire
+transfer subject and the amount that was received. Given this information, the
+backend can detect and report any irregularities that might arise.
+
+Tipping
+-------
+
+.. index:: tip
+.. index:: grant
+.. index:: pick up
+
+Taler does not only allow a Website to be paid, but also to make voluntary,
+non-contractual payments to visitors, called *tips*. Such tips could be
+granted as a reward for filling in surveys or watching advertisements. For
+tips, there is no contract, tips are always voluntary actions by the Web
+site that do not arise from a contractual obligation. Before a Web site
+can create tips, it must establish a reserve. Once a reserve has been
+established, the merchant can *grant* tips, allowing wallets to *pick up*
+the tip.
+
+Reserves
+--------
+
+.. index:: reserve
+.. index:: close
+
+A *reserve* is a pool of electronic cash at an exchange under the control of
+a private key. Merchants withdraw coins from a reserve when granting
+tips. A reserve is established by first generating the required key material
+in the merchant backend, and then wiring the desired amount of funds to the
+exchange.
+
+An exchange will automatically *close* a reserve after a fixed period of time
+(typically about a month), wiring any remaining funds back to the merchant.
+
Installation
============
@@ -211,17 +351,17 @@ Installing the GNU Taler exchange
After installing GNUnet, you can download and install the exchange as
follows:
-::
+ ::
- $ git clone https://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
+ $ git clone https://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
If you did not specify a prefix, the exchange will install to ``/usr/local``,
which requires you to run the last step as ``root``. You have to specify
@@ -244,18 +384,18 @@ The following steps assume all dependencies are installed.
Use the following commands to download and install the merchant backend:
-::
+ ::
- $ git clone https://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
+ $ git clone https://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
If you did not specify a prefix, the exchange will install to
``/usr/local``, which requires you to run the last step as ``root``.
@@ -287,7 +427,7 @@ On Debian jessie, only GNU libmicrohttpd needs to be compiled from
source. To install dependencies on Debian jesse, run the following
commands:
-::
+ ::
# apt-get install \
autoconf \
@@ -313,7 +453,7 @@ commands:
For more recent versions of Debian, you should instead run:
-::
+ ::
# apt-get install \
autoconf \
@@ -587,7 +727,7 @@ Sample backend configuration
The following is an example for a complete backend configuration:
-::
+ ::
[TALER]
CURRENCY = KUDOS
@@ -634,9 +774,9 @@ Launching the backend
.. index:: taler-merchant-httpd
Assuming you have configured everything correctly, you can launch the
-merchant backend as ``$USER`` using:
+merchant backend as ``$USER`` using
-::
+ ::
$ taler-merchant-httpd
@@ -647,13 +787,13 @@ system for how to start and stop daemons.
If everything worked as expected, the command
-::
+ ::
$ curl http://localhost:8888/
should return the message
-::
+ ::
Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
@@ -662,21 +802,19 @@ Production systems should be configured to bind to a UNIX domain socket
and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__.
-.. _Instances:
+.. index:: instance
+.. _Instance-setup:
-Instances
-=========
+Instance setup
+==============
-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 at least the "default" instance.
+Before using the backend, you must at least configure the "default" instance.
Instances can be configured by POSTing the necessary requests to the
backend. To create a first instance, create a file ``instance.json``
-with an `InstanceConfigurationMessage`:
+with an `InstanceConfigurationMessage`
-::
+ ::
{
payto_uris : [ "payto://iban/IBANNUMBERHERE" ],
@@ -693,7 +831,8 @@ with an `InstanceConfigurationMessage`:
You can then create the instance using:
-::
+ ::
+
$ wget --post-file=instance.json http://localhost:8888/private/instances
The base URL for the instance will then be
@@ -719,14 +858,6 @@ The bank account information is provided in the form of a ``payto://``-URL.
See RFC XXXX for the format of ``payto://``-URLs.
-.. _Inventory:
-
-Inventory management
-====================
-
-
-
-
.. _Secure-setup:
@@ -736,14 +867,26 @@ Secure setup
.. index:: security
.. index:: TLS
-For additional security, you may want to have the backend bind to a UNIX
-domain socket and use an HTTP reverse proxy for TLS termination:
+The Taler backend does not include even the most basic forms of
+access control or transport layer security. Thus, production
+setups **must** deploy the Taler backend behind an HTTP(S) server
+that acts as a *reverse proxy*, performs TLS termination and
+authentication and then forwards requests to the backend.
+
+Using UNIX domain sockets
+-------------------------
+
+To ensure that the merchant backend is not exposed directly to the network,
+you should bind the backend to a UNIX domain socket:
::
$ taler-config -s MERCHANT -o SERVE -V UNIX
$ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+Reverse proxy configuration
+---------------------------
+
Assuming your domain name is /example.com/ and you have TLS configured,
a possible reverse proxy directive for Nginx would be:
@@ -757,7 +900,25 @@ a possible reverse proxy directive for Nginx would be:
Leave out the last line if your Nginx reverse proxy does not have HTTPS
enabled. Make sure to restart the /taler-merchant-httpd/ process after
-changing the configuration.
+changing the ``SERVE`` configuration.
+
+Access control
+--------------
+
+All endpoints with /private/ in the URL must be restricted to authorized users
+of the respective instance. Specifically, the HTTP server must be configured
+to only allow access to ``$BASE_URL/private/`` to the authorized users of the
+default instance, and to ``$BASE_URL/instances/$ID/private/`` to the
+authorized users of the instance ``$ID``.
+
+How access control is done (TLS client authentication, HTTP basic or digest
+authentication, etc.) is completely up to the merchant and does not matter to
+the Taler merchant backend.
+
+Note that all of the other endpoints (without /private/) are expected to be
+fully exposed to the Internet, and wallets may have to interact with those
+endpoints directly without client authentication.
+
Upgrade procedure