completing merchant config

3 files changed, 108 insertions, 23 deletions

diff --git a/api-merchant.rst b/api-merchant.rst
index 8815e750..a0c4b938 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -17,6 +17,8 @@
   @author Florian Dold
   @author Christian Grothoff
 
+.. _merchant-api:
+
 ============
 Merchant API
 ============
@@ -70,7 +72,7 @@ The Frontent HTTP API
       // maximum fees merchant agreed to cover as per the contract
       max_fee: Amount;
 
-      // The merchant instance which is going to receive the final wire transfer. See paragraph `Merchant Instances`
+      // The merchant instance which is going to receive the final wire transfer. See :ref:`instances-lab`
       receiver: string;
 
       // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT
@@ -227,7 +229,7 @@ The following API are made available by the merchant's `backend` to the merchant
   **Request:**
 
   :query id: ID of the transaction we want to trace (an integer)
-  :query receiver: identificative token for the merchant instance which is to be tracked (optional). See :ref:`instances`.
+  :query receiver: identificative token for the merchant instance which is to be tracked (optional). See :ref:`instances-lab`. This information is needed because the request has to be signed by the merchant, thus we need to pick the instance's private key.
 
   **Response:**
 
@@ -285,20 +287,6 @@ Encodings
 
 Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
 
-.. _instances:
-
-------------------------------------------
-Merchant Instances (To be moved elsewhere)
-------------------------------------------
-
-Any backend can account for multiple bank accounts, and we call `instance` or `receiver` (interchangeably)
-any of those bank accounts. The backend needs that due to the ability we give to a merchant to route money
-(he earns through Taler) to multiple bank accounts, depending on his will. For example, a donation shop using
-Taler needs to know any bank account of any entity which is going to receive money through his website. That
-happens because when the merchant deposits coins to the exchange, he must provide bank details to it about the
-money receiver, see :ref:`deposit-par`.
-
-
 .. _contract:
 
 ------------------
diff --git a/operate-exchange.rst b/operate-exchange.rst
index b276d06d..007f57aa 100644
--- a/operate-exchange.rst
+++ b/operate-exchange.rst
@@ -48,8 +48,8 @@ The exchange works with three types of keys:
 
 `sign keys`: the following two options under `[exchange_keys]` section control `sign keys`:
 
-* `lookahead_sign`: How long should one signing key be used?
-* `signkey_duration`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap.
+* `signkey_duration`: How long should one signing key be used?
+* `lookahead_sign`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. See :ref:`keys-duration`.
 
 .. note::
   `signkeys` will be used in future versions of Taler.
diff --git a/operate-merchant.rst b/operate-merchant.rst
index 572c7d6d..d795c78d 100644
--- a/operate-merchant.rst
+++ b/operate-merchant.rst
@@ -23,15 +23,19 @@ Configuration
 
 The following data and facilities have to be set up, in order to run an exchange:
 
-* Keying
+* Serving
 * Currency
 * Database
-* Instances
 * Exchanges
+* Keying
+* Bank account
+* Instances
 
-------
-Keying
-------
+In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.
+
+-------
+Serving
+-------
 
 The merchant backend can serve HTTP over both TCP and UNIX domain socket.
 
@@ -70,3 +74,96 @@ possible in two ways:
 
   [merchantdb-postgres]
   config = postgres:///talerdemo
+
+---------
+Exchanges
+---------
+
+------
+Keying
+------
+
+The option `keyfile` under section `[merchant-instance-default]` is the path to the
+merchant's :ref:`default instance <instances-lab>` private key. This key is needed to
+sign certificates and other messages sent to wallets and exchanges.
+To generate a 100% compatible key, it is recommended to use the ``gnunet-ecc`` tool.
+
+------------
+Bank account
+------------
+
+This piece of information is used when the merchant redeems coins to the exchange.
+That way, the exchange will know to which bank account it has to transfer real money.
+The merchant must specify which system it wants receive wire transfers with. We support
+a `test` wire format so far, and supporting `SEPA` is among our priorities.
+
+The wire format is specified in the option `wireformat` under section `[merchant]`,
+and the wire details are given via a JSON file, whose path must be indicated in the
+option `X_response_file` under section `[default-wireformat]`, where `X` matches
+the chosen wireformat. In our demo, we have::
+
+  [merchant]
+  ..
+  wireformat = test
+  ..
+
+  [default-wireforma]
+  test_response_file = ${TALER_CONFIG_HOME}/merchant/wire/test.json
+
+The file `test.json` obeys to the following specification
+
+.. code-block:: tsref
+
+  interface WireDetails {
+    // matches wireformat
+    type: string; 
+
+    // base URL of the merchant's bank
+    bank_uri: string;
+
+    // merchant's signature (unused, can be any value)
+    signature: string; 
+
+    // merchant's account number at the bank
+    account_number: Integer;
+    
+    // the salt (unused, can be any value)
+    salt: any;
+  }
+
+As an example, `test.json` used in our demo is shown below::
+
+  {
+  "type": "test",
+  "bank_uri": "https://bank.test.taler.net/",
+  "sig": "MERCHANTSIGNATURE",
+  "account_number": 6,
+  "salt": "SALT"
+  }
+
+
+
+.. _instances-lab:
+
+---------
+Instances
+---------
+
+In Taler, multiple shops can rely on the same :ref:`merchant backend <merchant-arch>`.
+In Taler terminology, each of those shops is called `(merchant) instance`. Any instance
+is defined by its private key and its wire details. In order to add the instance `X` to
+the merchant backend, we have to add the sections `[merchant-instance-X]` and `[X-wireformat]`,
+and edit them as we did for the `default` instance. For example, in our demo we add the
+instance `Tor` as follows::
+  
+  [merchant-instance-Tor]
+  KEYFILE = ${TALER_DATA_HOME}/merchant/tor.priv
+  
+  ..
+
+  [Tor-wireformat]
+  TEST_RESPONSE_FILE = ${TALER_CONFIG_HOME}/merchant/wire/tor.json
+
+Please note that :ref:`Taler messagging<merchant-api>` is designed so that the merchant
+frontend can instruct the backend on which instance has to be used in the various operations.
+This information is optional, and if not given, the backend will act as the `default` instance.