Merge branch 'master' of git+ssh://git.taler.net/docs

3 files changed, 52 insertions, 14 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 7d7a784e..1f96ae62 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1418,7 +1418,7 @@ Creating orders
   .. note::
 
     This endpoint does not return a URL to redirect your user to confirm the
-    payment.  In order to get this URL use :http:get:/orders/$ORDER_ID.  The
+    payment.  In order to get this URL use :http:get:`/orders/$ORDER_ID`.  The
     API is structured this way since the payment redirect URL is not unique
     for every order, there might be varying parameters such as the session id.
 
diff --git a/frags/taler-payment-cycle.rst b/frags/taler-payment-cycle.rst
new file mode 100644
index 00000000..9c7d1302
--- /dev/null
+++ b/frags/taler-payment-cycle.rst
@@ -0,0 +1,37 @@
+The Taler payment cycle involves six parties:
+(a) customer,
+(b) exchange,
+(c) merchant,
+(d) customer's bank,
+(e) exchange's bank,
+(f) merchant's bank.
+
+The exchange is the central entity that mediates the wire transfer of real
+currency between (d), (e), (f) by way of *coins*, cryptographically secure
+tokens passed between (a), (b), (c).
+
+There are six steps to a Taler payment cycle.
+
+In step 1, (a) directs (d) to make real funds available to (b).
+
+In step 2, (d) does a wire transfer of real funds to (e), fulfilling the
+request from step 1.  (b) generates coins corresponding to those real funds;
+these are called the *reserve*.
+
+In step 3, (a) *withdraws* coins, either wholly or partially, from (b).  These
+coins are kept in a *wallet* under control of (a).  The coins in the wallet
+are anonymous.
+
+In step 4, (a) authorizes payment of coins from the wallet to (c).  This
+transfers payment coins from the wallet to (c), and change coins from (b) to
+the wallet (unless the payment amount exactly matches the denomination of the
+coins in the wallet).
+
+In step 5, (c) *deposits* coins into (b).  These coins are still anonymous,
+although the transaction itself is not anonymous.
+
+In step 6, (b) directs (e) to wire transfer real funds corresponding to the
+accumulated deposited coins to (f).
+
+NB: The Taler payment cycle is part of the Taler payment system, which
+includes also an auditor component, not described here.
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index e27c6569..0d98583c 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -71,24 +71,24 @@ special currency “KUDOS” and includes its own special bank.
 The Taler software stack for a merchant consists of four main
 components:
 
--  A frontend which interacts with the customer’s browser. The frontend
+-  A *frontend* which interacts with the customer’s browser. The frontend
    enables the customer to build a shopping cart and place an order.
    Upon payment, it triggers the respective business logic to satisfy
    the order. This component is not included with Taler, but rather
    assumed to exist at the merchant.
    The :ref:`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
+-  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
    not included with Taler, but rather assumed to exist at the
    merchant. The :ref:`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
+-  A Taler-specific payment *backend* which makes it easy for the frontend
    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.
+-  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
@@ -555,7 +555,7 @@ https://exchange.demo.taler.net/:
 Database
 ^^^^^^^^
 
-In principle is possible for the backend to support different DBMSs.
+In principle it is possible for the backend to support different DBMSs.
 The option
 
 .. code-block:: ini
@@ -657,7 +657,7 @@ section, the following options need to be configured:
           -V KUDOS
 
 Note that multiple exchanges can be added to the system by using different
-tokens in place of ``demo`` in the example above. Note that all of the
+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.
@@ -701,9 +701,9 @@ that section, the following options need to be configured:
 
 
 Note that multiple auditors can be added to the system by using different
-tokens in place of ``demo`` in the example above. Note that all of the
+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
+currency from the ``TALER`` section, the auditor is ignored.  If you need to
 support multiple currencies, you need to configure a backend per currency.
 
 
@@ -810,7 +810,8 @@ In order to receive payments, the merchant backend needs to
 communicate bank account details to the exchange.
 
 The bank account information is provided in the form of a ``payto://``-URI.
-See RFC 8905 for the format of ``payto://``-URIs.
+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/>`_.
@@ -854,7 +855,7 @@ create a file ``instance.json`` with an `InstanceConfigurationMessage`
    }
 
 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
+``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
@@ -1216,9 +1217,9 @@ is always tied to a particular instance. To create a reserve with
        -m http://localhost:8888/instances/default
 
 The above command assumes that the merchant runs on localhost on
-port 8888. The current implementation of the tool does not yet support
-transmission of authentication information to the backend
-(`see bug 6418 <https://bugs.gnunet.org/view.php?id=6418>`_).
+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.