addressing #4600 and other parts with the same problem

1 files changed, 29 insertions, 8 deletions

diff --git a/api-merchant.rst b/api-merchant.rst
index 71f9a302..9c1adf9b 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -23,9 +23,9 @@ Merchant API
 
 Before reading the API reference documentation, it is suggested to read the :ref:`merchant-arch`
 
-------------------------------
+---------------------
 The Frontent HTTP API
-------------------------------
+---------------------
 
 .. http:get:: contract_url
 
@@ -71,6 +71,9 @@ 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`
+      receiver: string;
+
       // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT
       merchant_sig: EddsaSignature;
 
@@ -143,20 +146,20 @@ The following API are made available by the merchant's `backend` to the merchant
 
   **Request:**
 
-  The `proposition` that is to be sent from the frontend is a `contract` object without the fields
+  The `proposition` that is to be sent from the frontend is a `contract` object *without* the fields
 
   * `exchanges`
   * `auditors`
   * `H_wire`
   * `merchant_pub`
 
-  The `backend` then completes this information based on its configuration.
+  The frontend may or may not provide a `receiver` field in the proposition, depending on its logic.
+  The ``default`` instance will be used if no `receiver` field is found by the backend.
 
   **Response**
 
   :status 200 OK:
-    The backend has successfully created the contract.  It responds with an :ref:`offer <offer>`. This request should virtually always be successful.
-  On success, the `frontend` should pass this response verbatim to the wallet.
+    The backend has successfully created the contract.  It responds with an :ref:`offer <offer>`. On success, the `frontend` should pass this response verbatim to the wallet.
 
   :status 403 Forbidden:
     The frontend used the same transaction ID twice.  This is only allowed if the response from the backend was lost ("instant" replay), but to assure that frontends usually create fresh transaction IDs this is forbidden if the contract was already paid.  So attempting to have the backend sign a contract for a contract that was already paid by a wallet (and thus was generated by the frontend a "long" time ago), is forbidden and results in this error.  Frontends must make sure that they increment the transaction ID properly and persist the largest value used so far.
@@ -225,7 +228,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`.
   **Response:**
 
   :status 200 OK:
@@ -282,6 +285,20 @@ Encodings
 
 Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
 
+.. _instances:
+
+------------------
+Merchant Instances
+------------------
+
+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:
 
 Offer and Contract
@@ -359,7 +376,11 @@ The `contract` must have the following structure:
       // More info about the merchant, see below
       merchant: Merchant;
 
-      // The hash of the merchant's wire details.
+      // Which instance is participating in this contract. See the paragraph `Merchant Instances`.
+      // This field is optional, as the "default" instance is not forced to provide any `receiver` identificator.
+      receiver: string;
+
+      // The hash of the merchant instance's wire details.
       H_wire: HashCode;
 
       // Any exchanges audited by these auditors are accepted by the merchant.