update merchant documentation

2 files changed, 41 insertions, 25 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 5c50709a..c56cff0c 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -24,10 +24,7 @@ Merchant Backend API
 ====================
 
 WARNING: This document describes the version 1 of the merchant backend
-API, which is NOT yet implemented at all!
-
-TODO: https://bugs.gnunet.org/view.php?id=5987#c15127
-      is not yet addressed by this specification!
+API, which is NOT yet implemented in Git master!
 
 The ``*/private/*`` endpoints are only supposed to be exposed
 to the merchant internally, and must not be exposed on the
@@ -35,7 +32,8 @@ Internet.
 
 Most endpoints given here can be prefixed by a base URL that includes the
 specific instance selected (BASE_URL/instances/$INSTANCE/).  If
-``/instances/`` is missing, the default instance is to be used.
+``/instances/`` is missing from the request path, the ``default`` instance is
+used.
 
 .. contents:: Table of Contents
 
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 6ffd193d..8652e13d 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -74,13 +74,13 @@ components:
    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 `Merchant API Tutorial <#merchant-api-tutorial>`__ gives an
+   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
    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 `Merchant Backend API <#merchant-api>`__ provides
+   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
@@ -110,7 +110,7 @@ the Taler backend.
 A typical deployment will additionally include a full-blown Web server (like
 Apache or Nginx). Such a Web server would be responsible for TLS termination
 and access control to the /private/ API endpoints of the merchant backend.
-Please carefully review the section on `Secure setup <#Secure-setup>`__ before
+Please carefully review the section on :ref:`Secure setup <Secure-setup>` before
 deploying a Taler merchant backend to production.
 
 
@@ -799,7 +799,7 @@ should return the message
 
 Please note that your backend is right now likely globally reachable.
 Production systems should be configured to bind to a UNIX domain socket
-and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__.
+and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`.
 
 
 .. index:: instance
@@ -810,9 +810,9 @@ Instance setup
 
 Before using the backend, you must at least configure the "default" instance.
 
-Instances can be configured by POSTing the necessary requests to the
-backend.  To create a first instance, create a file ``instance.json``
-with an `InstanceConfigurationMessage`
+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`
 
   ::
 
@@ -841,7 +841,7 @@ instances by changing the "id" value to identifies other than "default".
 
 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 `Merchant Backend API documentation <#merchant-api>`__.
+in the :ref:`Merchant Backend API documentation <merchant-api>`.
 
 
 Accounts
@@ -959,17 +959,13 @@ Tipping visitors
 
 .. index:: tipping
 
-NOTE: This section is dated and should be reviewed!
-
 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 four basic steps that must happen to tip a visitor.
-
-FIXME: write current explanation!
+There are three basic steps that must happen to tip a visitor.
 
 .. _Fund-the-reserve:
 
@@ -977,7 +973,27 @@ Fund the reserve
 ----------------
 
 .. index:: reserve
-.. index:: close
+
+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:
+
+  ::
+
+     $ 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. 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>`_).
+
+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:
 
@@ -986,7 +1002,7 @@ In our example, the output for the wire transfer subject is:
    QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
 
 You now need to make a wire transfer to the exchange’s bank account
-using the public key as the wire transfer subject.
+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
@@ -1008,7 +1024,8 @@ 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 “/private/reserves/$RID/tip-authorize” API of the backend. To authorize a
+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:
 
@@ -1037,7 +1054,8 @@ missconfigured instances or a lack of remaining funds for tipping.
 Picking up of the tip
 ---------------------
 
-The wallet will POST a JSON object to the shop’s “/tips/$TIP/pickup” handler.
+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.
 
@@ -1128,7 +1146,7 @@ Note that, in this stage of development, the file
 component. For example, both an exchange and a bank can read values from
 it.
 
-The repository ``git://taler.net/deployment`` contains examples of
+The `deployment repository <https://git.taler.net/deployment>`_ contains examples of
 configuration file used in our demos. See under ``deployment/config``.
 
    **Note**
@@ -1416,12 +1434,12 @@ Before starting to build the merchant’s image, make sure a
 “docker-machine“ instance is up and running.
 
 Because all of the Docker source file are kept in our “deployment“
-repository, we start by checking out the ``git://taler.net/deployment``
+repository, we start by checking out the ``git://git.taler.net/deployment``
 codebase:
 
 ::
 
-   $ git clone git://taler.net/deployment
+   $ git clone git://git.taler.net/deployment
 
 Now we actually build the merchant’s image. From the same directory as
 above: