diff options
author | Christian Grothoff <christian@grothoff.org> | 2020-06-26 17:42:30 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2020-06-26 17:42:30 +0200 |
commit | 18012a7d0568cda761b6f7886fa445e4e8f8ff65 (patch) | |
tree | 09da500abf890c22d58f0a63a6a788a16a8f3c14 | |
parent | 704a5e1eceed1a6f73d7998ce3068e848ac03e87 (diff) | |
download | docs-18012a7d0568cda761b6f7886fa445e4e8f8ff65.tar.gz docs-18012a7d0568cda761b6f7886fa445e4e8f8ff65.tar.bz2 docs-18012a7d0568cda761b6f7886fa445e4e8f8ff65.zip |
terminology for merchant backend
-rw-r--r-- | taler-merchant-api-tutorial.rst | 23 | ||||
-rw-r--r-- | taler-merchant-manual.rst | 289 |
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 |