summaryrefslogtreecommitdiff
path: root/taler-merchant-manual.rst
diff options
context:
space:
mode:
Diffstat (limited to 'taler-merchant-manual.rst')
-rw-r--r--taler-merchant-manual.rst1546
1 files changed, 698 insertions, 848 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index f6b2e1a0..48605a55 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1,7 +1,30 @@
-.. _ffoobar:
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2023 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero 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 Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
+.. _taler-merchant-backend-operator-manual:
+
+Merchant Backend Operator Manual
+################################
+
+.. contents:: Table of Contents
+ :depth: 1
+ :local:
-GNU Taler Merchant Backend Operator Manual
-##########################################
Introduction
============
@@ -9,20 +32,8 @@ Introduction
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.
+.. include:: frags/about-taler.rst
+
.. _About-this-manual:
@@ -36,17 +47,6 @@ 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 manual 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.
-
-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.
-
.. _Architecture-overview:
Architecture overview
@@ -56,20 +56,19 @@ Architecture overview
.. index:: 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.
+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. Taler can also be used as a regional currency; for such scenarios, the
+Taler system also includes its own stand-alone bank.
.. index:: frontend
.. index:: back-office
.. index:: backend
.. index:: DBMS
-.. index:: Postgres
+.. index:: PostgreSQL
-The Taler software stack for a merchant consists of four main
-components:
+The Taler software stack for a merchant consists of four main components:
- A *frontend* which interacts with the customer’s browser. The frontend
enables the customer to build a shopping cart and place an order.
@@ -90,14 +89,14 @@ components:
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 implementation only supports
- Postgres, but the code could be easily extended to support another
- DBMS. Please review the Postgres documentation for details on
+ PostgreSQL, but the code could be easily extended to support another
+ DBMS. Please review the PostgreSQL documentation for details on
how to configure the database.
The following image illustrates the various interactions of these key
components:
-.. image:: arch-api.png
+.. image:: images/arch-api.png
.. index:: RESTful
@@ -107,13 +106,13 @@ 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 are encapsulated within
-the Taler backend.
+the Taler merchant 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 :ref:`Secure setup <Secure-setup>` before
-deploying a Taler merchant backend to production.
+Apache or Nginx). Such a Web server would be responsible for TLS termination and
+access control to the ``/private/`` and ``/management/`` API endpoints of the
+merchant backend. Please carefully review the section on :ref:`secure setup
+<Secure-setup>` before deploying a Taler merchant backend into production.
Terminology
@@ -126,21 +125,44 @@ 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).
+The backend allows a single HTTP server to support multiple independent shops
+with distinct business entities sharing a single backend. An *instance* is
+the name or identifier that allows the single HTTP server to determine which
+shop a request is intended for. Each instance has its own base URL in the
+REST API of the merchant backend (``/instances/$INSTANCE/``). Each instance
+can use its own bank accounts and keys for signing contracts. All major
+accounting functionality is separate per instance. Access to each instance is
+controlled via a bearer token (to be set in the HTTP "Authorization" header).
+All instances share the same *database*, top-level HTTP(S) address and the
+main Taler configuration (especially the accepted *currency* and *exchanges*).
-Accounts
---------
+ .. note::
+
+ This documentation does not use the term "user" or "username" in
+ conjunction with instances as that might create confusion between
+ instances with paying customers using the system. We also do not use the
+ term "account" in conjunction with instances, as that might cause
+ confusion with bank accounts. That said, conceptually it is of course
+ acceptable to consider instances to be the "users" or "accounts" of a
+ merchant backend and the bearer token is equivalent to a passphrase.
+
+.. _instance-bank-account:
-.. index:: account
+Instance Bank Accounts
+----------------------
+
+.. index:: Bank 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.
+*accounts*. When configuring the bank account of an instance, one should
+ideally also provide the address and credentials of an HTTP service
+implementing the :ref:`Taler Bank Revenue HTTP API
+<taler-bank-merchant-http-api>`. Given such a service, the GNU Taler merchant
+backend can automatically reconcile wire transfers from the exchange to the
+merchant's bank account with the orders that are being settled.
+
+This documentation exclusively uses the term *account* for the bank
+accounts of a merchant or shop that may be associated with an instance.
Inventory
---------
@@ -153,21 +175,26 @@ Inventory
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.
+*units*. Inventory can be finite (physical stock) or infinite (for digital
+products). Products may include previews (images) to be shown to the user as
+well as other meta-data. Inventory management allows the frontend to *lock*
+products, reserving a number of units from stock 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.
+include products in orders that are not in the inventory. The frontend
+can also override prices of products in the inventory or set a total price
+for an order that is different from the price of the sum of the products
+in the order.
+
Orders and Contracts
--------------------
.. index:: order
+.. index:: terms
.. index:: contract
.. index:: claim
.. index:: pay
@@ -176,8 +203,13 @@ Orders and Contracts
.. 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.
+In Taler, users pay merchants for *orders*. An order is first created by the
+merchant. To create an order, the merchant must specify the specific *terms*
+of the order. Order *terms* include details such as the total amount to be
+paid, payment fees the merchant is willing to cover, the set of products to
+deliver, a delivery location and many other details. The `merchant API
+specification <contract-terms>`_ specifies the full set of possible order
+terms.
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
@@ -189,270 +221,216 @@ purchase the same product.
To prevent unauthorized wallets from claiming an order, merchants can specify
that claims require authorization in the form of a *claim token*. This is
useful in case the order ID is predictable (say because an existing order ID
-scheme from the merchant frontend is used) and at the same time malicious
-actors claiming orders is problematic (say because of limited stocks). The use
-of claim tokens is optional, but if a claim token is used, it must be provided
-to the wallet as part of the order URI.
-
-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.
+scheme with predictable order IDs from the merchant frontend is used) and at
+the same time malicious actors claiming orders is problematic (say because of
+limited stocks). The use of claim tokens is optional, but if a claim token is
+used, it must be provided to the wallet as part of the order URI.
+
+Additionally, when stocks are limited, you can configure Taler to set a
+*product lock* on items (say, while composing the shopping cart). These
+locks will ensure that the limited stock is respected when making offers
+to consumers.
+
+A wallet may *pay* for a claimed order, at which point the order turns into a
+(paid) *contract*. Orders have a configurable expiration date (the
+``pay_deadline``) after which the commercial offer expires and any stock of
+products *locked* by the order will be automatically released, allowing the
+stock to be sold in other orders. When an unpaid order expires, the customer
+must request a fresh order if they still want to make a purchase.
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 after the
customer paid and before 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.
+Taler exchange. The *wire deadline* specifies the latest point in time by
+which an exchange must wire the funds, while the (earlier) *refund deadline*
+specifies the earliest point in time when an exchange may wire the funds.
+Thus, refunds are always possible between the time of purchase and the
+refund deadline, but may remain possible until the wire deadline.
-Transfers
----------
+Contract information is kept for legal reasons in the merchant database. The
+main legal reason is typically to provide tax records in case of a tax audit.
+After the *legal expiration* (by default: a decade), contract information is
+deleted when running the garbage collector using ``taler-merchant-dbinit``.
-.. 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
---------
+.. _template:
-.. 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
-============
-
-This chapter describes how to install the GNU Taler merchant backend.
-
-.. _Generic-instructions:
+Templates
+---------
-Generic instructions for installation from source
--------------------------------------------------
+.. index:: Template
-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.
+Usually, a merchant must use an authenticated endpoint to create an order and
+then share the link to the order with a wallet. Templates are a mechanism that
+allows wallets to create their own orders directly, using a public endpoint.
+The template fixes some properties of the contracts created from it, while
+other details may be left for the customer to provide. Templates are useful
+in cases where the point-of-sale of a merchant is offline (and thus cannot
+setup an order), or even in cases where a simple static QR code is desired to
+accept payments or donations.
-.. _Installation-of-dependencies:
+When generating a template, the "summary" text of the contract and the
+"amount" to be paid by the customer can be fixed or left for the customer to
+specify. If the customer is expected to provide either or both of these
+values, the template link (or QR code) can specify a default value. For
+example, a cafeteria with a fixed price lunch may use a "lunch" template with
+both values fixed to the lunch price and the "lunch" product, a bakery might
+fix the summary to "baked goods" but allow the customer to enter the amount
+based on the total price of the items being bought, and a charity may allow
+donating an arbitrary amount and summary message while also suggesting default
+values.
-Installation of dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If an offline merchant wants to confirm that a customer did actually pay the
+agreed amount using an order derived from a template, they can associate an
+OTP device with the template.
-The following packages need to be installed before we can compile the
-backend:
-.. include:: frags/list-of-dependencies.rst
+.. _otp-device:
-- GNU Taler exchange (see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)
+OTP Devices
+-----------
-Except for the last two, these are available in most GNU/Linux distributions
-and should just be installed using the respective package manager. Be careful
-with GNU libmicrohttpd; here, some distributions only include an older version
-that will not work.
+.. index:: OTP
+.. index:: TOTP
-While you are in the GNU Taler exchange
-`download directory <http://ftpmirror.gnu.org/taler/>`__,
-you might as well also download the tarball for GNU Taler merchant.
+A One-Time-Password (OTP) generator is a device or application that generates
+a 4 to 8 digit code typically used for authentication. The widely used TOTP
+standard is described in `RFC 6238 <https://www.rfc-editor.org/rfc/rfc6238>`_.
+For GNU Taler merchant backends, OTP devices are used as a way to assure a
+merchant without network connectivity that a customer made a digital
+payment. The idea is described in depth in our `SUERF Policy Brief
+<https://www.suerf.org/suer-policy-brief/69851/practical-offline-payments-using-one-time-passcodes>`_.
+To use this method, a merchant must configure the OTP device's shared secret
+in the merchant backend, and then associate the OTP device with a
+:ref:`template`. Once the customer has paid, they are given a list of OTP
+codes which must be shown to the merchant who can check that at least one of
+the codes matches their OTP device, proving that the customer made the
+payment.
-GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format.
-The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match.
-Exceptions to this general rule are documented in the release notes.
-For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1.
-The following sections will provide detailed instructions for installing
-the ``libgnunetutil`` and GNU Taler exchange dependencies.
+Transfers
+---------
-.. _Installing-libgnunetutil:
+.. index:: transfer
+.. index:: wire transfer
-Installing GNUnet
-^^^^^^^^^^^^^^^^^
+The Taler backend can be used to verify that the exchange correctly wired all
+of the funds to the merchant. However, if no :ref:`Taler Bank Revenue HTTP API
+<taler-bank-merchant-http-api>` was provided for the respective bank account,
+the backend does not have access to the incoming wire transfers of the
+merchant's bank account. In this case, merchants should 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.
-.. index:: GNUnet
-.. include:: frags/installing-gnunet.rst
+Webhooks
+--------
-There is no need to actually run a GNUnet peer to use the Taler merchant
-backend -- all the merchant needs from GNUnet is a number of headers and
-libraries!
+.. index:: webhook
+A webhook is a pre-defined HTTP request that the GNU Taler merchant backend
+will make upon certain events, such as an order being paid or refunded. When
+the configured event happens, the merchant backend will make an HTTP request
+to the endpoint configured in the webhook configuration, possibly sending
+selected data about the event to the respective Web service. Webhooks can be
+used to trigger additional business logic outside of the GNU Taler merchant
+backend.
-.. _Installing-the-GNU-Taler-exchange:
-Installing the GNU Taler exchange
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Installation
+============
-.. index:: exchange
+This chapter describes how to install the GNU Taler merchant backend.
-.. include:: frags/installing-taler-exchange.rst
+.. _Generic-instructions:
-There is no need to actually run a Taler exchange to use the Taler merchant
-backend -- all the merchant needs from the Taler exchange is a few headers and
-libraries!
+Installing the GNU Taler binary packages on Debian
+--------------------------------------------------
+.. include:: frags/installing-debian.rst
-.. _Installing-the-GNU-Taler-merchant-backend:
+.. include:: frags/apt-install-taler-merchant.rst
-Installing the GNU Taler merchant backend
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. index:: backend
+Installing the GNU Taler binary packages on Trisquel
+----------------------------------------------------
-.. include:: frags/installing-taler-merchant.rst
+.. include:: frags/installing-trisquel.rst
-Installing the GNU Taler binary packages on Debian
+Installing the GNU Taler binary packages on Ubuntu
--------------------------------------------------
-.. include:: frags/installing-debian.rst
+.. include:: frags/installing-ubuntu.rst
.. include:: frags/apt-install-taler-merchant.rst
-Installing the GNU Taler binary packages on Ubuntu
---------------------------------------------------
+Installing from source
+----------------------
-.. include:: frags/installing-ubuntu.rst
+The following instructions will show how to install a GNU Taler
+merchant backend from source.
-.. include:: frags/apt-install-taler-merchant.rst
+The package sources can be find in our
+`download directory <http://ftpmirror.gnu.org/taler/>`__.
+.. include:: frags/semver.rst
-.. _Installing-Taler-on-Debian-GNU_002fLinux:
+First, the following packages need to be installed before we can compile the
+backend:
-Installing Taler on Debian GNU/Linux from source
-------------------------------------------------
+.. include:: frags/list-of-dependencies.rst
-.. index:: Wheezy
-.. index:: Jessie
-.. index:: Stretch
-.. index:: Debian
+.. include:: frags/installing-gnunet.rst
-Debian wheezy is too old and lacks most of the packages required.
-Debian jessie is better, but still lacks PostgreSQL 9.6.
+.. include:: frags/install-before-check.rst
-On Debian stretch, only GNU libmicrohttpd needs to be compiled from
-source. To install dependencies on Debian stretch, run the following
-commands:
+There is no need to actually run a GNUnet peer to use the Taler merchant
+backend -- all the merchant needs from GNUnet is a number of headers and
+libraries!
-.. code-block:: console
+.. include:: frags/installing-taler-exchange.rst
- # apt-get install \
- libqrencode-dev \
- libsqlite3-dev \
- libltdl-dev \
- libunistring-dev \
- libsodium-dev \
- libargon2-0-dev \
- libcurl4-gnutls-dev \
- libgcrypt20-dev \
- libjansson-dev \
- libpq-dev \
- postgresql-9.6
- # 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
-
-For more recent versions of Debian, you should instead run:
+There is no need to actually run a Taler exchange to use the Taler merchant
+backend -- all the merchant needs from the Taler exchange is a few headers and
+libraries!
-.. code-block:: console
+.. include:: frags/install-before-check.rst
- # apt-get install \
- libqrencode-dev \
- libsqlite3-dev \
- libltdl-dev \
- libunistring-dev \
- libsodium-dev \
- libargon2-dev \
- libcurl4-gnutls-dev \
- libgcrypt20-dev \
- libjansson-dev \
- libpq-dev \
- postgresql-9.6 \
- libmicrohttpd-dev
+.. include:: frags/installing-taler-merchant.rst
-Note that stretch requires ``libargon2-0-dev``,
-while later versions of Debian require ``libargon2-dev``.
+.. include:: frags/install-before-check.rst
-For the rest of the installation, follow the generic installation
-instructions starting with the installation of libgnunetutil. Note that
-if you used the Debian stretch instructions above, you need to pass
-``--with-microhttpd=/usr/local/`` to all ``configure`` invocations.
-How to configure the merchant’s backend
-=======================================
+How to configure the merchant backend
+=====================================
-.. index:: taler-config
.. index:: 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 ``$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 ``taler-config``
-commands given as examples.
+database that the backend should use. By default, the file
+``$HOME/.config/taler.conf`` is where the Web shop administrator specifies
+configuration values that augment or override the defaults.
+Note that when using our binary packages, the systemd service files
+force the use of ``/etc/taler/taler.conf`` as the main configuration file.
.. include:: frags/configuration-format.rst
-.. include:: frags/using-taler-config.rst
-
-
.. _Backend-options:
Backend options
---------------
.. index:: DBMS
-.. index:: Postgres
+.. index:: PostgreSQL
.. index:: UNIX domain socket
.. index:: TCP
.. index:: port
@@ -463,25 +441,30 @@ Backend options
.. index:: wire format
The following table describes the options that commonly need to be
-modified. Here, the notation ``[$section]/$option`` denotes the option
-``$option`` under the section ``[$section]`` in the configuration file.
+modified. Here, the notation ``[$SECTION]/$OPTION`` denotes the option
+``$OPTION`` under the section ``[$SECTION]`` in the configuration file.
Service address
^^^^^^^^^^^^^^^
-The following option sets the transport layer address used by the
-merchant backend:
+The service address specifies where the taler-merchant-httpd should listen for
+requests. When using the Debian/Ubuntu packages, these options will already be
+configured correctly for the included Nginx and Apache configurations and will
+not need any changes.
+
+The following option sets the transport protocol used by the merchant backend:
.. code-block:: ini
- [MERCHANT]/SERVE = TCP | UNIX
+ [MERCHANT]
+ SERVE = unix # or tcp
-If given,
+If this option is set to
-- ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT``
+- ``tcp`` then we need to set the TCP port in ``[MERCHANT]/PORT``;
-- ``UNIX``, then we need to set the unix domain socket path and mode
+- ``unix`` then we need to set the unix domain socket path and mode
in ``[MERCHANT]/UNIXPATH`` and ``[MERCHANT]/UNIXPATH_MODE``. The
latter takes the usual permission mask given as a number, e.g. 660
for user/group read-write access.
@@ -493,10 +476,26 @@ the backend to the network.
To run the Taler backend on TCP port 8888, use:
-.. code-block:: console
+.. code-block:: ini
+
+ [MERCHANT]
+ SERVE = tcp
+ PORT = 8888
+
+.. note::
- $ taler-config -s MERCHANT -o SERVE -V TCP
- $ taler-config -s MERCHANT -o PORT -V 8888
+ If you need to change where the taler-merchant-httpd listens for requests,
+ you should edit ``/etc/taler/merchant-overrides.conf``. By default, the
+ Taler merchant package will use a UNIX domain socket at
+ ``/run/taler/merchant-httpd/merchant-http.sock``. For the best possible
+ security it is recommended to leave this in place and configure a reverse
+ proxy (Nginx or Apache) as described below.
+
+ When using the Debian/Ubuntu packages, the use of a UNIX domain socket
+ is already pre-configured in the ``/etc/taler/conf.d/merchant.conf``
+ configuration file. Suitable reverse proxy configuration
+ file templates (``taler-merchant``) are be installed in the
+ respective ``sites-available`` directories of Apache and Nginx.
@@ -508,15 +507,26 @@ specified using the option
.. code-block:: ini
- [TALER]/CURRENCY
+ [TALER]
+ CURRENCY = EUR # or USD, ...
-For testing purposes, the currency MUST match “KUDOS” so that tests
-will work with the Taler demonstration exchange at
-https://exchange.demo.taler.net/:
+When testing with the Taler demonstration exchange at
+https://exchange.demo.taler.net/ you must set this
+value to ``KUDOS``:
-.. code-block:: console
+.. code-block:: ini
+
+ [TALER]
+ CURRENCY = KUDOS
+
+.. note::
- $ taler-config -s TALER -o CURRENCY -V KUDOS
+ When using the Debian/Ubuntu packages, these options should be
+ configured in the ``/etc/taler/taler.conf`` configuration file
+ (alternatively, you can also edit ``/etc/taler/merchant-overrides.conf``).
+ However, you must edit the ``taler.conf`` file manually and **must not**
+ use ``taler-config`` to do this, as that would inline the include
+ directives and destroy the carefully setup path structure.
Database
@@ -527,7 +537,8 @@ The option
.. code-block:: ini
- [MERCHANT]/DB
+ [MERCHANT]
+ DB = postgres
specifies which DBMS is to be used. However, currently only the value
``postgres`` is supported. This is also the default.
@@ -535,23 +546,32 @@ specifies which DBMS is to be used. However, currently only the value
In addition to selecting the DBMS software, the backend requires
DBMS-specific options to access the database.
-For postgres, you need to provide:
+.. note::
+
+ The **taler-merchant-dbconfig** tool can be used to automate the database
+ setup. When using the Debian/Ubuntu packages, the user should already have
+ been created, so you can just run the tool without any arguments and should
+ have a working database configuration.
+
+
+For the ``postgres`` backend, you need to specify:
.. code-block:: ini
- [MERCHANTDB-postgres]/CONFIG
+ [merchantdb-postgres]
+ CONFIG = "postgres:///taler-merchant"
-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:
+This option specifies a PostgreSQL access path, typically using the format
+``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the PostgreSQL
+database you want to use (here, ``taler-merchant`` on the local machine).
+Suppose ``$USER`` is the name of the user who will run the backend process
+(usually ``taler-merchant-httpd``). Then, you need to first run:
.. code-block:: console
$ sudo -u postgres createuser -d $USER
-as the Postgres database administrator (usually ``postgres``) to
+as the PostgreSQL database administrator (usually ``postgres``) to
grant ``$USER`` the ability to create new databases. Next, you should
as ``$USER`` run:
@@ -562,29 +582,18 @@ as ``$USER`` run:
to create the backend’s database. Here, ``$DBNAME`` must match the
database name given in the configuration file.
-To configure the Taler backend to use this database, run:
-
-.. code-block:: console
-
- $ taler-config -s MERCHANTDB-postgres -o CONFIG \
- -V postgres:///$DBNAME
-
-Now you should create the tables and indices. To do this, run as ``$USER``:
+Now you should be able to create the tables and indices. To do this, run as
+``$USER`` (usually ``taler-merchant-httpd``):
.. code-block:: console
$ taler-merchant-dbinit
-
-You can improve your security posture if you now REVOKE the rights to CREATE,
+You may improve your security posture if you now REVOKE the rights to CREATE,
DROP or ALTER tables from ``$USER``. However, if you do so, please be aware
that you may have to temporarily GRANT those rights again when you update the
merchant backend. For details on how to REVOKE or GRANT these rights, consult
-the Postgres documentation.
-
-Commands, like ``taler-merchant-dbinit``, that support the ``-l LOGFILE``
-command-line option, send logging output to standard error by default.
-See :doc:`manpages/taler-merchant-dbinit.1` for more information.
+the PostgreSQL documentation.
.. include:: frags/db-stores-sensitive-data.rst
@@ -601,79 +610,47 @@ section, the following options need to be configured:
- The ``EXCHANGE_BASE_URL`` option specifies the exchange’s base URL.
For example, to use the Taler demonstrator, specify:
- .. code-block:: console
+ .. code-block:: ini
- $ taler-config -s MERCHANT-EXCHANGE-demo \
- -o EXCHANGE_BASE_URL \
- -V https://exchange.demo.taler.net/
+ [merchant-exchange-kudos]
+ EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/"
- The ``MASTER_KEY`` option specifies the exchange’s master public key
in base32 encoding. For the Taler demonstrator, use:
- .. code-block:: console
+ .. code-block:: ini
- $ taler-config -s MERCHANT-EXCHANGE-demo \
- -o MASTER_KEY \
- -V FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
+ [merchant-exchange-kudos]
+ MASTER_KEY = "GNRJCH0HYKN59939JC0CJ2JDC7ZNEBSATJFF00CVS3WPG4TQEA7G"
+
+ You can find out this key by running ``curl https://exchange.demo.taler.net/keys | jq .master_public_key``.
- The ``CURRENCY`` option specifies the exchange’s currency.
For the Taler demonstrator, use:
- .. code-block:: console
-
- $ taler-config -s MERCHANT-EXCHANGE-demo \
- -o CURRENCY \
- -V KUDOS
+ .. code-block:: ini
-Note that multiple exchanges can be added to the system by using different
-tokens in place of ``demo`` in the examples above. Note that all of the
-exchanges must use the same currency: If the currency does not match the main
-currency from the ``TALER`` section, the exchange is ignored. If you need to
-support multiple currencies, you need to configure a backend per currency.
-
-
-
-Auditor
-^^^^^^^
-
-To add an auditor to the list of trusted auditors (which implies
-that all exchanges audited by this auditor will be trusted!)
-you create a section with a name that starts with “MERCHANT-AUDITOR-”. In
-that section, the following options need to be configured:
-
-- The ``AUDITOR_BASE_URL`` option specifies the auditor’s base URL.
- For example, to use the Taler demonstrator's auditor, specify:
-
- .. code-block:: console
-
- $ taler-config -s MERCHANT-AUDITOR-demo \
- -o AUDITOR_BASE_URL \
- -V https://exchange.demo.taler.net/
-
-- The ``AUDITOR_KEY`` option specifies the auditor's public key
- in base32 encoding. For the Taler demonstrator, use:
+ [merchant-exchange-kudos]
+ CURRENCY = "KUDOS"
- .. code-block:: console
- $ taler-config -s MERCHANT-AUDITOR-demo \
- -o AUDITOR_KEY \
- -V DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11
-
-- The ``CURRENCY`` option specifies the auditor’s currency.
- For the Taler demonstrator, use:
-
- .. code-block:: console
+Note that multiple exchanges can be added to the system by using different
+identifiers in place of ``KUDOS`` in the example above. Note that all of the
+exchanges actually used will use the same currency: If the currency does not
+match the main ``CURRENCY`` option from the ``taler`` section, the respective
+``merchant-exchange-`` section is automatically ignored. If you need support
+for multiple currencies, you need to deploy one backend per currency.
- $ taler-config -s MERCHANT-AUDITOR-demo \
- -o CURRENCY \
- -V KUDOS
+The merchant already ships with a default configuration that contains the
+``merchant-exchange-kudos`` section from above.
+.. note::
-Note that multiple auditors can be added to the system by using different
-tokens in place of ``demo`` in the examples above. Note that all of the
-auditors must use the same currency: If the currency does not match the main
-currency from the ``TALER`` section, the auditor is ignored. If you need to
-support multiple currencies, you need to configure a backend per currency.
+ Manually setting up exchanges is only recommended under special
+ circumstances. In general, GNU Taler distributions will include trustworthy
+ exchanges (for each currency) in the default configuration, and there is
+ rarely a good reason for trusting an exchange that has no relationship
+ with the GNU Taler development team.
.. _Sample-backend-configuration:
@@ -687,41 +664,31 @@ The following is an example for a complete backend configuration:
.. code-block:: ini
- [TALER]
+ [taler]
CURRENCY = KUDOS
- [MERCHANT]
+ [merchant]
SERVE = TCP
PORT = 8888
DATABASE = postgres
- [MERCHANTDB-postgres]
- CONFIG = postgres:///donations
+ [merchantdb-postgres]
+ CONFIG = postgres:///taler-merchant
- [merchant-exchange-NAME]
+ [merchant-exchange-kudos]
EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
- # If currency does not match [TALER] section, the exchange
+ # If currency does not match [taler] section, the exchange
# will be ignored!
CURRENCY = KUDOS
- [merchant-auditor-NAME]
- AUDITOR_BASE_URL = https://auditor.demo.taler.net/
- AUDITOR_KEY = DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11
- # If currency does not match [TALER] section, the auditor
- # will be ignored!
- CURRENCY = KUDOS
-
-Given the above configuration, the backend will use a database named
-``donations`` within Postgres.
+Given the above configuration, the backend will use a PostgreSQL database
+named ``donations`` running on the same host.
The backend will deposit the coins it receives to the exchange at
https://exchange.demo.taler.net/, which has the master key
``FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0``.
-Please note that ``doc/config.sh`` will walk you through all
-configuration steps, showing how to invoke ``taler-config`` for each of
-them.
.. _Launching-the-backend:
@@ -732,28 +699,48 @@ 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 (to provide a trivial example):
.. code-block:: console
- $ taler-merchant-httpd
-
-To ensure the process runs always in the background and also after rebooting,
-you should use systemd, cron or some other init system of your operating
-system to launch the process. Consult the documentation of your operating
-system for how to start and stop daemons.
+ $ taler-merchant-httpd &
+ $ taler-merchant-webhook &
+ $ taler-merchant-wirewatch &
+ $ taler-merchant-depositcheck &
+ $ taler-merchant-exchange &
+
+To ensure these processes run always in the background and also after
+rebooting, you should use systemd, cron or some other init system of your
+operating system to launch the process. You should also periodically re-start
+these services to prevent them from exhausing the memory utilization of the
+PostgreSQL database. Consult the documentation of your operating system for
+how to start and stop daemons.
+
+.. note::
+
+ When using the Debian/Ubuntu packages, the systemd configuration
+ will already exist. You only need to enable and start the service
+ using ``systemctl enable taler-merchant.target`` and
+ ``systemctl start taler-merchant.target``. Additionally, you should
+ review the ``/etc/apache2/sites-available/taler-merchant.conf``
+ or ``/etc/nginx/sites-available/taler-merchant`` (these files
+ contain additional instructions to follow), symlink it to
+ ``sites-enabled/`` and restart your HTTP server. After that, you
+ should be able to visit the merchant backend at the respective
+ HTTP(S) endpoint.
If everything worked as expected, the command
.. code-block:: console
- $ curl http://localhost:8888/config
+ $ wget -O - http://localhost:8888/config
should return some basic configuration status data about the service.
-Please note that your backend is right now likely globally reachable. You can either:
+Please note that your backend might then be globally reachable without
+any access control. You can either:
- * Use the ``--auth=$TOKEN`` command-line option to set an access token to be provided in an ``Authorize: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified.
+ * Use the ``--auth=$TOKEN`` command-line option to **taler-merchant-httpd** to set an access token to be provided in an ``Authorize: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified.
* Set the ``TALER_MERCHANT_TOKEN`` environment variable to ``$TOKEN`` for the same effect. This method has the advantage of ``$TOKEN`` not being visible as a command-line interface to other local users on the same machine.
* Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token!
@@ -764,82 +751,96 @@ and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`
.. index:: instance
.. _Instance-setup:
+
Instance setup
==============
-Before using the backend, you must at least configure the "default" instance.
+We recommend the use of the single-page administration application (SPA) that
+is served by default at the base URL of the merchant backend. You can use it
+to perform all steps described in this section (and more!), using a simple Web
+interface. Alternatively, you can also use the ``wget`` commands given below.
+Regardless of which approach you use, the first step for using the backend
+involves the creation of a ``default`` instance. The ``default`` instance can
+also create, configure or delete other instances, similar to the ``root``
+account on UNIX. When no instance exists and ``taler-merchant-httpd`` was
+started without the ``--auth`` option, then the backend is reachable without
+any access control (unless you configured some in the reverse proxy).
-KUDOS Accounts
---------------
+The following documentation shows how to handle any instance. Thus, if you
+want to have multiple instances, you may need to perform the steps multiple
+times, once for each instance.
-The main configuration data that must be provided for each instance
-is the bank account information.
+.. note::
-In order to receive payments, the merchant backend needs to
-communicate bank account details to the exchange.
+ A potential security concern is that normal API usage leaks instance existence.
+ This means unauthorized users can distinguish between the case where the
+ instance does not exist (HTTP 404) and the case where access is denied
+ (HTTP 403).
+ This is concern can be addressed using a properly configured
+ :ref:`reverse proxy <reverse-proxy-configuration>`.
-The bank account information is provided in the form of a ``payto://``-URI.
-See `RFC 8905 <https://tools.ietf.org/html/rfc8905>`_
-for the format of ``payto://``-URIs.
-For first tests, you should sign up for a KUDOS bank
-account at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.
-In this case, the ``payto://``-URI will be of the form
-``payto://x-taler-bank/bank.demo.taler.net/$USERNAME`` where ``$USERNAME``
-must be replaced with the name of the account that was established
-at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.
+Instance setup with the SPA
+---------------------------
+
+In order to setup an instance, you need the merchant backend to already be
+running, and you must either have the credentials for the "default" instance,
+or no instance must be configured at all yet.
+
+To start, point your browser to ``$PROTO://backend.$DOMAIN_NAME/``, replacing
+"$PROTO" with "https" or (rarely) "http" and "$DOMAIN_NAME" with your
+organizations DNS domain or subdomain.
+
+.. note::
+
+ The label "backend" here is also just a suggestion, your administrator
+ can in principle choose any name.
+You should be welcomed by the following merchant backoffice page:
-IBAN Accounts
--------------
+.. image:: screenshots/merchant_first_login.png
-When deploying Taler with the real banking system, you primarily need to
-change the currency of the configuration from KUDOS to the actual currency
-(such as EUR, USD, CHF) and provide a ``payto://``-URI of your real bank
-account. In Europe, this will involve knowing your IBAN number. If you have an
-IBAN, the corresponding ``payto://``-URI is simply ``payto://iban/$IBAN`` where
-``$IBAN`` must be replaced with the actual IBAN number.
+After supplying the required fields, primarily the name of your organization
+and the desired access token, click ``confirm``. You can change the instance
+settings later via the ``Settings`` entry in the menu on the left.
-Setup
-------
+Instance setup without the Web interface
+----------------------------------------
-With the knowledge of the ``payto://``-URI, instances can be configured by POSTing
-a request to :http:post:`/private/instances`. To create a first instance,
-create a file ``instance.json`` with an `InstanceConfigurationMessage`
+Instances can be created by POSTing a request to ``/management/instances``
+without using the Web interface. This could be useful if you want to create
+many instances programmatically. To create an instance without the Web
+interface create a file ``instance.json`` with an
+`InstanceConfigurationMessage`:
.. code-block:: json
{
- "payto_uris" : [ "$PAYTO_URI" ],
"id" : "default",
- "name": "example.com",
+ "name": "Example Inc.",
"address": { "country" : "zz" },
"auth": { "method" : "external"} ,
"jurisdiction": { "country" : "zz" },
- "default_max_wire_fee": "KUDOS:1",
- "default_wire_fee_amortization": 100,
- "default_max_deposit_fee": "KUDOS:1",
+ "use_stefan": true,
"default_wire_transfer_delay": { "d_ms" : 1209600000 },
"default_pay_delay": { "d_ms" : 1209600000 }
}
-In the text above, you must replace ``$PAYTO_URI`` with your actual
-``payto://``-URI. Also, be sure to replace ``KUDOS`` with the fiat currency if the
-setup is for an actual bank. The ``name`` field will be shown as the name of
-your shop. The ``address`` field is expected to contain your shop's physical
-address. The various defaults specify defaults for transaction fees your shop
-is willing to cover, how long offers made to the customer are valid, and how
-long the exchange has before it must wire the funds to your bank
-account. Those defaults can be modified for individual orders.
-For details, see the :ref:`contract terms <contract-terms>` specification.
+The ``name`` field will be shown as the name of your shop. The
+``address`` field is expected to contain your shop's physical address. The
+various defaults specify defaults for transaction fees your shop is willing to
+cover, how long offers made to the customer are valid, and how long the
+exchange has before it must wire the funds to your bank account. Those
+defaults can be modified for individual orders. For details, see the
+:ref:`contract terms <contract-terms>` specification.
You can then create the instance using:
.. code-block:: console
- $ wget --post-file=instance.json http://localhost:8888/private/instances
+ $ wget --post-file=instance.json http://localhost:8888/management/instances
The base URL for the instance will then be
``http://localhost:8888/instances/default``. You can create additional
@@ -849,6 +850,125 @@ Endpoints to modify (reconfigure), permanently disable (while keeping the data)
or purge (deleting all associated data) instances exist as well and are documented
in the :ref:`Merchant Backend API documentation <merchant-api>`.
+.. _instance-account-setup:
+
+Instance account setup
+======================
+
+Before you can use an instance productively, you need to configure one or more
+bank accounts. These bank accounts will be provided to the Taler exchange
+operator to tell it where to wire the income from your sales. Every bank
+account has an associated *wire method* which determines how an exchange can
+transfer the funds. The most commonly supported wire method is *iban*, which
+implies that bank accounts are identified by IBAN numbers and wire transfers
+are to be executed between IBAN accounts. For regional currency setups, the
+wire method could also be *x-taler-bank*.
+
+.. note::
+
+ When using a regional currency, you need to first create a bank account at
+ the regional bank. You may need to contact the respective administrator who
+ can set one up. After being able to login to the new bank account, you can
+ see your bank account number by clicking on the ``Welcome, $USERNAME``
+ message in the profile page. Next to the bank account number, you can find
+ a convenient button to copy the number to the clipboard.
+
+Not every exchange will support every *wire method*, and if you do not add a
+bank account with a wire method that is supported by a particular exchange,
+then you will not be able to receive payments via that exchange even if you
+configured the merchant backend to trust that exchange.
+
+The simplest way to configure an account is to use the Web interface which has
+specific forms for different wire methods. First, select ``Bank account`` at
+the left of the page. The following page should be shown:
+
+.. image:: screenshots/no_default_account_yet.png
+
+Click on the blue "+" sign on the top right of the page to add a new
+bank account. The following page should appear:
+
+.. image:: screenshots/enter_instance_details.png
+
+First, you should select the wire method, after which the dialog will show you
+additional fields specific to the wire method. For example, if youchoose
+``iban`` as the account type, the following page should appear:
+
+.. image:: screenshots/instance_iban_config.png
+
+Specifying the revenue gateway with username and password is optional and
+discussed in section :ref:`automatic-settlement-data-import` below.
+
+After providing the details and confirming, the shop is ready to generate orders
+and accept payments.
+
+
+
+Detecting Settlement: Manually Adding Transfers
+-----------------------------------------------
+
+The exchange may aggregate many small amounts into one larger wire transfer.
+If you want to safely determine for which orders have been settled (final
+payment from the exchange has been received), the backend must learn about the
+wire transfers made into your bank account. Basically, as a secure system, we
+do not simply trust a claim by the exchange that it would transfer the money,
+but we allow each merchant to check settlements.
+
+An easy (but somewhat tedious) way to check settlements is to manually add
+every wire transfer that a merchant bank account has received from the
+exchange with the total amount and the wire transfer subject. Given this
+information, the merchant backend will inquire with the exchange which
+individual payments were aggregated, check that the total amount is correct,
+and will then flag the respective contracts as wired.
+
+You can manually enter wire transfers under ``Transfers``. However, this is
+tedious, and so if your banking setup supports it, we highly recommend
+using the automatic settlement data import.
+
+.. _automatic-settlement-data-import:
+
+Automatic Settlement Data Import
+--------------------------------
+
+To automatically import settlement data, you need to provide the merchant
+backend with the address and access credentials of a
+:ref:`taler-bank-merchant-http-api` for each bank account of an instance. The
+revenue API endpoint will allow the merchant backend to obtain a list of all
+incoming wire transfers into your bank account and automatically import them
+into the list of confirmed wire transfers.
+
+Note that setting up a revenue API endpoint will usually require you to first
+ask your bank for EBICS access and to set up :ref:`libeufin-nexus` to provide
+the revenue API endpoint. The :ref:`libeufin-bank` used by regional currency
+setups also provides a revenue API endpoint at
+``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``. Thus, when using a
+regional currency setup, simply use the ``$BANK_URL`` of your bank and specify
+your bank login name and password in the :ref:`instance-account-setup` dialog.
+
+
+Manually creating an order using the SPA
+========================================
+
+Click on ``Orders`` at the top left corner of the merchant backoffice page; the
+following page should appear
+
+.. image:: screenshots/create_orders.png
+
+After having filled the required fields, the interface should show the
+following page with the related links to check the status of the order and let
+wallets pay for it.
+
+.. image:: screenshots/payment_links.png
+
+In order to test the setup, it should be now possible to use the command line wallet
+to withdraw Taler coins and spend them to pay for the order we just created.
+
+In practice, you will rarely if ever setup orders manually like this. Instead,
+a `GNU Taler e-commerce front-end
+<https://taler.net/en/docs.html#extensions>`_ or the
+:ref:`taler-merchant-pos-app` will do this on-demand. Here, you will only need
+to provide the respective front-ends with the URL of your instance
+(e.g. ``https://backend.$DOMAIN/instances/$NAME``) and your access token.
+
.. _Secure-setup:
@@ -858,11 +978,12 @@ Secure setup
.. index:: security
.. index:: TLS
-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.
+The Taler backend is deliberately simple in terms of support for access
+control or transport layer security (TLS). 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
-------------------------
@@ -870,10 +991,11 @@ 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:
-.. code-block:: console
+.. code-block:: ini
- $ taler-config -s MERCHANT -o SERVE -V UNIX
- $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+ [MERCHANT]
+ SERVE = unix
+ UNIXPATH = "/some/path/here.sock"
Do not use a UNIX domain socket path in "/tmp": systemd (or other init
systems) may give Web servers a private "/tmp" thereby hiding UNIX domain
@@ -881,9 +1003,11 @@ sockets created by other users/processes in "/tmp".
If UNIX domain sockets are for some reason not possible, you *may* use a
host-based firewall to block access to the TCP port of the merchant backend,
-but this is *not recommended*. Relying on NAT or network firewalls for access
-control is gross negligence.
+but this is *not recommended*. If you do need a TCP socket, you should
+instead strongly consider using the "BIND_TO" option to at least bind it only
+to "localhost".
+.. _reverse-proxy-configuration:
Reverse proxy configuration
---------------------------
@@ -932,155 +1056,135 @@ Note that the above again assumes your domain name is ``example.com`` and that
you have TLS configured. Note that you must add the ``https`` header unless
your site is not available via TLS.
-The above configuration(s) are both incomplete. You must still additionally
-setup access control!
-
-
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``.
+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.
+By default, the GNU Taler merchant backend simply requires the respective
+HTTP requests to include an "Authorization" header with a "Bearer" token
+set to the respective shared secret which must begin with "secret-token:"
+(following RFC 8959).
-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.
-
-Nginx
-^^^^^
+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.
-For Nginx, you can implement token-based merchant backend authentication as
-follows:
-.. code-block:: nginx
+Status code remapping
+---------------------
- location ~ /private/ {
- if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") {
- return 401;
- }
- proxy_pass ...; // as above
- }
+Normal API usage leaks instance existence information. Distinguishing between
+404 (Not found) and 403 (Forbidden) is useful for diagnostics.
-Here, ``SECURITYTOKEN`` should be replaced with the actual shared secret. Note
-that the ``~`` ensures that the above matches all endpoints that include the
-string ``/private/``. If you only run a single instance, you could simply
-specify ``/private/`` without the ``~`` to only configure the access policy for
-the default instance.
+For higher security (by leaking less information), you can add the following
+fragment, which remaps all 404 response codes to 403.
-If you are running different instances on the same backend, you
-likely will want to specify different access control tokens for
-each instance:
+Nginx
+^^^^^
.. code-block:: nginx
- location ~ ^/instances/foo/private/ {
- if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") {
- return 401;
- }
- proxy_pass ...; # as above
- }
- location ~ ^/instances/bar/private/ {
- if ($http_authorization !~ "(?i)ApiKey BARTOKEN") {
- return 401;
- }
- proxy_pass ...; # as above
- }
- location /private/ {
- if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") {
- return 401;
- }
- proxy_pass ...; # as above
- }
- location ~ /private/ {
- return 401; # access to instances not explicitly configured is forbidden
- }
+ error_page 404 =403 /empty.gif;
Apache
^^^^^^
-For Apache, you should first enable ``mod_rewrite``:
+.. code-block:: apacheconf
-.. code-block:: console
+ cond %{STATUS} =404
+ set-status 403
- $ a2enmod rewrite
-Then, you can restrict to an access control token using:
+Customization
+=============
-.. code-block:: apacheconf
+Legal conditions for using the service
+--------------------------------------
- <Location "/">
- RewriteEngine On
- RewriteCond "%{HTTP:AUTHORIZATION}" "!=SECURITYTOKEN"
- RewriteRule "(.+)/private/" "-" [F]
+.. include:: frags/legal.rst
- ProxyPass "unix:/some/path/here.sock|http://example.com/"
- </Location>
+.. _MerchantTemplateCustomization:
-Here, ``SECURITYTOKEN`` should be replaced with the actual shared secret. Note
-that the ``(.+)`` ensures that the above matches all endpoints that include the
-string ``/private/``. If you only run a single instance, you could simply
-specify ``/private/`` without the ``~`` to only configure the access policy for
-the default instance.
+Template Customization
+----------------------
-If you are running different instances on the same backend, you
-likely will want to specify different access control tokens for
-each instance:
+The installation process will install various HTML templates to be served to
+trigger the wallet interaction. You may change those templates to your own
+design. The templating language used is `Mustach
+<https://gitlab.com/jbol/mustach>`__, and the templates are in the
+``share/taler/merchant/templates/`` directory.
-.. code-block:: apacheconf
+The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the
+name of the template and ``$LANG`` is the 2-letter language code of the
+template. English templates must exist and will be used as a fallback. If the
+browser (user-agent) has provided language preferences in the HTTP header and
+the respective language exists, the correct language will be automatically
+served.
- <Location "/instances/foo/">
- RewriteEngine On
- RewriteCond "%{HTTP:AUTHORIZATION}" "!=FOOTOKEN"
- RewriteRule "/instances/foo/private/" "-" [F]
+The following subsections give details about each of the templates. The
+subsection titles are the ``$NAME`` of the respective template.
- ProxyPass ... # as above
- </Location>
+request_payment
+^^^^^^^^^^^^^^^
- <Location "/instances/bar/">
- RewriteEngine On
- RewriteCond "%{HTTP:AUTHORIZATION}" "!=BARTOKEN"
- RewriteRule "/instances/bar/private/" "-" [F]
+Page shown to request the user to make a payment.
- ProxyPass ... # as above
- </Location>
+This template is instantiated using the following information:
- <Location "/">
- RewriteEngine On
- RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN"
- RewriteRule "/private/" "-" [F]
- RewriteRule "(.+)/private/" "-" [F] # reject all others
+ * taler_pay_uri: String; the ``taler://pay/`` URI that must be given
+ to the wallet to initiate the payment
- ProxyPass ... # as above
- </Location>
+ * taler_pay_qrcode_svg: Image; an SVG image of the QR code with the
+ ``taler_pay_uri``.
-Please note that these are simply examples of how one could use Nginx or
-Apache2 for access control. Both HTTP servers support many other forms of
-authentication, including TLS client certificates, HTTP basic and digest
-authentication and others, which can all be used (possibly in combination) to
-restrict access to the internal API to authorized clients.
+ * order_summary: String; a text summarizing the order
-System administrators are strongly advised to test their access control
-setup before going into production!
+ * order_status_url: URL of the merchant backend where the order status
+ can be found, useful for long-polling to check if the order has been paid
-Customization
-=============
+offer_refund
+^^^^^^^^^^^^
-Templates
----------
+Page shown to offer a customer a refund.
+
+This template is instantiated using the following information:
+
+ * taler_refund_uri: String; the ``taler://pay/`` URI that must be given
+ to the wallet to initiate the payment
+
+ * taler_refund_qrcode_svg: Image; an SVG image of the QR code with the
+ ``taler_pay_uri``.
-The installation process will install various HTML templates to be served
-to trigger the wallet interaction. You may change those templates to your
-own design. The templating language used is Mustach, and the templates
-are in the ``share/taler/merchant/templates/`` directory.
+ * refund_amount: Amount; how much did the merchant refund
+ * refund_taken: Amount; how much did the customer already take back in refunds
+
+ * order_summary: String; a text summarizing the order
+
+
+
+show_order_details
+^^^^^^^^^^^^^^^^^^
+
+Page shown to the user when they go back to the payment page but
+no payment is required and no refund is present.
+
+This template is instantiated using the following information:
+
+ * order_summary: String; a text summarizing the order
+
+ * contract_terms: Object; the full contract terms (shoud probably
+ not be shown in full!)
+
+ * refund_amount: Amount; how much did the merchant refund
+
+ * refund_taken: Amount; how much did the customer already take back in refunds
Static files
------------
@@ -1111,7 +1215,8 @@ Limitations
All of the static files must fit into memory and it must be possible for the
process to hold open file handles for all of these files. You may want
to increase the ``ulimit`` of the ``taler-merchant-httpd`` process if you have
-templates for many languages.
+many static files. Note that Mustach templates do not increase the number of
+open files.
The backend determines the MIME type based on the file's extension. The list
of supported extensions is hard-coded and includes common text and image
@@ -1126,8 +1231,8 @@ features.
Upgrade procedure
=================
-This is the general upgrade procedure. Please see the release notes
-for your specific version to check if a particular release has special
+This section describes the general upgrade procedure. Please see the release
+notes for your specific version to check if a particular release has special
upgrade requirements.
Please note that upgrades are ONLY supported for released version of the
@@ -1135,8 +1240,8 @@ merchant. Attempting to upgrade from or to a version in Git is not supported
and may result in subtle data loss.
To safely upgrade the merchant, you should first stop the existing
-``taler-merchant-httpd`` process, backup your merchant database (see Postgres
-manual), and then install the latest version of the code.
+``taler-merchant-httpd`` process, backup your merchant database (see
+PostgreSQL manual), and then install the latest version of the code.
If you REVOKED database permissions, ensure that the rights to CREATE,
DROP, and ALTER tables are GRANTed to ``$USER`` again. Then, run:
@@ -1146,126 +1251,21 @@ DROP, and ALTER tables are GRANTed to ``$USER`` again. Then, run:
$ taler-merchant-dbinit
to upgrade the database to the latest schema. After that, you may again
-REVOKE the database permissions. Finally, restart the HTTP service, either via
-your systemd or init system, or directly using:
-
-.. code-block:: console
-
- $ taler-merchant-httpd
-
-
-.. _Tipping-visitors:
-
-Tipping visitors
-================
-
-.. index:: 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 three basic steps that must happen to tip a visitor.
-
-.. _Fund-the-reserve:
-
-Fund the reserve
-----------------
-
-.. index:: reserve
-
-First, the reserve must be setup in the merchant backend. A reserve
-is always tied to a particular instance. To create a reserve with
-10 KUDOS at instance ``default`` using the demo exchange, use:
-
-.. code-block:: console
-
- $ taler-merchant-setup-reserve \
- -a KUDOS:10 \
- -e https://exchange.demo.taler.net/ \
- -m http://localhost:8888/instances/default
-
-The above command assumes that the merchant runs on localhost on
-port 8888.
-For more information, including how to transmit authentication information
-to the backend, see :doc:`manpages/taler-merchant-setup-reserve.1`.
-
-The command will output a ``payto://`` URI which specifies where to
-wire the funds and which wire transfer subject to use.
-
-FIXME: add full example output.
-
-In our example, the output for the wire transfer subject is:
-
-.. code-block:: none
-
- QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
-
-You now need to make a wire transfer to the exchange’s bank account
-using the given wire transfer subject.
-
-Make your wire transfer and (optionally) check at
-“https://exchange/reserves/QPE24X...” whether your transfer has arrived at the
-exchange.
-
-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 setup another reserve
-every other week to ensure one is always ready.
-
-.. _Authorize-a-tip:
-
-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 :http:post:`/private/reserves/$RESERVE_PUB/authorize-tip`
-API of the backend. To authorize a
-tip, the frontend has to provide the following information in the body of the
-POST request:
+REVOKE the database permissions. Finally, restart the merchant services
+processes, either via your systemd or init system, or directly.
-- The amount of the tip
-- The justification (only used internally for the back-office)
-- The URL where the wallet should navigate next after the tip was
- processed
-
-- The tip-pickup URL (see next section)
-
-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 special “402 Payment Required” response inside the ``X-Taler-Tip``
-header.
-
-The frontend should handle errors returned by the backend, such as
-misconfigured instances or a lack of remaining funds for tipping.
-
-.. _Picking-up-of-the-tip:
-
-Picking up of the tip
----------------------
-
-The wallet will POST a JSON object to the shop’s
-:http:post:`/tips/$TIP_ID/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.
+Advanced topics
+===============
+taler-config
+------------
+.. index:: taler-config
-Advanced topics
-===============
+.. include:: frags/using-taler-config.rst
.. _MerchantDatabaseScheme:
@@ -1281,159 +1281,47 @@ allowing administrators to purge records that are no longer required.
The database scheme used by the merchant looks as follows:
-.. image:: merchant-db.png
-
-
-
-Configuration format
---------------------
-
-.. index:: 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
-``${prefix}/share/taler/config.d/``, in ``.conf`` files. In order to override
-these defaults, the user can write a custom .conf file and either pass
-it to the component at execution time, or name it ``taler.conf`` and place
-it under ``$HOME/.config/``.
-
-A config file is a text file containing sections, and each section
-contains its values. The right format follows:
-
-.. code-block:: ini
-
- [section1]
- value1 = string
- value2 = 23
-
- [section2]
- value21 = string
- value22 = /path22
-
-Throughout any configuration file, it is possible to use ``$``-prefixed
-variables, like ``$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:
-``${VAR:-default}``. However, there are two ways a user can set
-``$``-prefixable variables:
-
-by defining them under a ``[paths]`` section, see example below,
-
-.. code-block:: ini
-
- [paths]
- TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
- ...
- [section-x]
- path-x = ${TALER_DEPLOYMENT_SHARED}/x
-
-or by setting them in the environment:
-
-.. code-block:: console
-
- $ export VAR=/x
-
-The configuration loader will give precedence to variables set under
-``[path]``, though.
-
-The utility ``taler-config``, which gets installed along with the
-exchange, serves to get and set configuration values without directly
-editing the ``.conf``. The option ``-f`` is particularly useful to resolve
-pathnames, when they use several levels of ``$``-expanded variables. See
-``taler-config --help``.
-
-Note that, in this stage of development, the file
-``$HOME/.config/taler.conf`` can contain sections for *all* the
-components. For example, both an exchange and a bank can read values from
-it.
-
-The `deployment repository <https://git.taler.net/deployment>`_ contains examples of
-configuration file used in our demos. See under ``deployment/config``.
-
- **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.
-
-.. _Using-taler_002dconfig:
+.. image:: images/merchant-db.png
-Using taler-config
-^^^^^^^^^^^^^^^^^^
-
-.. index:: taler-config
-
-The tool ``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:
-
-.. code-block:: console
-
- $ taler-config -s $SECTION
-
-to list all of the configuration values in section ``$SECTION``.
+.. _MerchantBenchmarking:
-Run:
+Benchmarking
+------------
-.. code-block:: console
+The merchant codebase offers the ``taler-merchant-benchmark`` tool to populate
+the database with fake payments. The main goal of the benchmarking tool is to
+serve as a starting point (!) for merchants that are interested in developing
+stress tests to see how far their infrastructure can scale. As is, it
+currently is not actually good at stressing the payment system.
- $ taler-config -s $section -o $option
+The ``taler-unified-setup.sh`` script can be used to launch all required
+services and clients. However, the resulting deployment is simplistic
+(everything on the local machine, one single-threaded process per service
+type) and not optimized for performance at all. However, this can still be
+useful to assess the performance impact of changes
+to the code or configuration.
-to extract the respective configuration value for option ``$option`` in
-section ``$section``.
-Finally, to change a setting, run:
+Various configuration files that can be used in the code snippets in this
+section can be found in the ``src/merchant-tools/`` directory of the
+merchant. These are generally intended as starting points. Note that the
+configuration files ending in ``.edited`` are created by
+``taler-unified-setup.sh`` and contain some options that are determined at
+runtime by the setup logic provided by ``taler-unified-setup.sh``.
-.. code-block:: console
+See :ref:`Taler Exchange Manual <Benchmark-choose-bank>` for how to use ``taler-unified-setup.sh`` to setup the system and in particular on how to specify the bank to be used.
- $ taler-config -s $section -o $option -V $value
-to set the respective configuration value to ``$value``. Note that you
-have to manually restart the Taler backend after you change the
-configuration to make the new configuration go into effect.
+Running taler-merchant-benchmark
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Some default options will use ``$``-variables, such as ``$DATADIR`` within
-their value. To expand the ``$DATADIR`` or other ``$``-variables in the
-configuration, pass the ``-f`` option to ``taler-config``. For example,
-compare:
+You can run the tool as follows:
.. code-block:: console
- $ taler-config -s PATHS \
- -o TALER_DATA_HOME
- $ taler-config -f -s PATHS \
- -o TALER_DATA_HOME
-
-While the configuration file is typically located at
-``$HOME/.config/taler.conf``, an alternative location can be specified
-to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c``
-option.
-
-
-
-Advanced experimental features
-==============================
-
-This section describes features that most merchants will not
-need, or will not need initially.
-
-.. _MerchantBenchmarking:
-
-Benchmarking
-------------
-
-The merchant codebase offers the ``taler-merchant-benchmark`` tool to
-populate the database with fake payments. This tool is in charge of
-starting a merchant, exchange, and bank processes, and provides them all
-the input to accomplish payments. Note that each component will use its
-own configuration (as they would do in production).
-
-The main goal of the benchmarking tool is to serve as a starting point (!) for
-merchants that are interested in developing stress tests to see how far their
-infrastructure can scale.
+ $ CONF=benchmark-rsa.conf
+ $ taler-unified-setup.sh -emwt -c "$CONF" -f -u exchange-account-1
+ $ time taler-merchant-benchmark ordinary -c "$CONF".edited -u exchange-account-1 -f -p 20
The current tool has already a few options, but we expect that to deliver
*relevant* results it will need to be customized to better reflect the
@@ -1442,47 +1330,16 @@ likely involve writing (C) code. We welcome contributions to make it easier
to customize the benchmark and/or to cover more realistic workloads from the
start.
-
-Benchmark setup
----------------
-
-The ``taler-merchant-benchmark`` tool will automatically launch and configure the
-exchange, (Python) bank and other tools required for the benchmark. However,
-the configuration file must be provided and have consistent options set. The
-options that require special care include the exchange's public key (which
-must match the private key in the file specified by the configuration), the
-currency (which must be consistent across the file), the denomination
-structure (which must enable payments in the range of 100ths of the unit
-currency (often called cents)). Furthermore, the benchmark will set the
-Exchange bank account password to be "x", so the configuration must also
-specify "x" for the passphrase. Finally, the bank must be configured to allow
-for substantial debt least the transactions by the benchmark run out of
-digital cash.
-
-A relatively minimal configuration could look like this:
-
-.. literalinclude:: merchant-benchmark.conf
-
-
-Note that the public key must match the exchange's
-private key and that the Postgres database must
-exist before launching the benchmark. You also
-will need to ensure that the Exchange's
-details are set up.
-For details, see the :ref:`Exchange Operator Manual <Bank-account>`.
-
-
-Running the benchmark command
------------------------------
-
The tool takes all of the values it needs from the command line, with
-one of them being mandatory:
+some of them being common to all subcommands:
-- ``--exchange-account=SECTION`` Specifies which configuration
+- ``--exchange-account-section=SECTION`` Specifies which configuration
section specifies the bank account for the exchange that
should be used for the benchmark. For the example
configuration above, the SECTION value provided must be
``exchange-account-exchange``.
+- ``--fakebank`` Specifies that the benchmark should expect to interact
+ with a fakebank (instead of libeufin).
The tool comes with two operation modes: *ordinary*, and *corner*.
The first just executes normal payments, meaning that it uses the
@@ -1491,8 +1348,10 @@ second gives the chance to leave some payments unaggregated, and also to
use merchant instances other than the default (which is, actually, the
one used by default by the tool).
-Note: the ability of driving the aggregation policy is useful for testing
-the back-office facility.
+.. note::
+
+ The ability to drive the aggregation policy is useful for testing
+ the back-office facility.
Any subcommand is also equipped with the canonical ``--help`` option, so
feel free to issue the following command in order to explore all the
@@ -1513,19 +1372,10 @@ interesting, there are:
perform *UN* (one coin) payments that will be left unaggregated.
As for the ``ordinary`` subcommand, it is worth explaining the following
-options:
+option:
- ``--payments-number=PN`` Instructs the tool to perform *PN* payments.
-- ``--tracks-number=TN`` Instructs the tool to perform *TN* tracking
- operations. Note that the **total** amount of operations will be two
- times *TN*, since "one" tracking operation accounts for
- ``/track/transaction`` and ``/track/transfer``. This command should
- only be used to see if the operation ends without problems, as no
- actual measurement of performance is provided (despite of the
- ’benchmark’ word used in the tool’s name).
-
-
Temporarily Abandoned Features
@@ -1586,5 +1436,5 @@ request to the merchant, for example:
.. code-block:: console
- $ curl http://$(docker-machine ip)/
+ $ wget -O - http://$(docker-machine ip)/
# A greeting message should be returned by the merchant.