more doc revision

1 files changed, 63 insertions, 31 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index a8dfd0e9..a12b1d7e 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -44,11 +44,11 @@ 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
@@ -56,8 +56,7 @@ special currency “KUDOS” and includes its own special bank.
 .. index:: DBMS
 .. 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.
@@ -95,13 +94,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/`` 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 to production.
+merchant backend. Please carefully review the section on :ref:`secure setup
+<Secure-setup>` before deploying a Taler merchant backend into production.
 
 
 Terminology
@@ -114,21 +113,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.
 
-.. index:: account
+
+Instance Bank Accounts
+----------------------
+
+.. index:: instance-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 `Taler Bank Merchant 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
 ---------
@@ -141,21 +163,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
@@ -164,8 +191,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