update merchant spec'

2 files changed, 73 insertions, 33 deletions

diff --git a/anastasis.rst b/anastasis.rst
index fc32343b..7c10d01f 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1564,24 +1564,62 @@ Expected new state:
 
 **select_challenge:**
 
+Selecting a challenge takes various formats, depending on the method.
+Specifically, in the case of a security question, the answer should
+already be provided.
+
+Arguments (example):
+
+.. code-block:: json
+
+    {
+        "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30"
+    }
+
+.. code-block:: json
+
+    {
+        "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30",
+        "answer": "answer to secure question"
+    }
+
+**pay:**
+
 Arguments (example):
 
 .. code-block:: json
 
     {
-        "challenge_index": 1
+        "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30"
     }
 
 
 **solve_challenge:**
 
+Solving a challenge takes various formats, depending on the method and
+what is known about the answer.
+
 Arguments (example):
 
 .. code-block:: json
 
     {
-        "challenge_index": 1,
-        "solution": "answer to secure question"
+        "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30",
+        "answer": "answer to secure question"
+    }
+
+.. code-block:: json
+
+    {
+        "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30",
+        "pin": 1234
+    }
+
+.. code-block:: json
+
+    {
+        "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30",
+        "hash": "SOMEBASE32ENCODEDHASHVALUE"
     }
 
 
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 76c97a4c..a49589ca 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -72,11 +72,10 @@ Examples:
    A public endpoint (explicit "default" instance):
    https://merchant-backend.example.com/instances/default/orders
 
-   Endpoint(s) to manage other instances:
+   Endpoint to manage other instances (ONLY for implicit "default" instance):
    https://merchant-backend.example.com/private/instances
-   https://merchant-backend.example.com/instances/default/private/instances
 
-   Unavailabe endponts (will return 404)
+   Unavailabe endponts (will return 404):
    https://merchant-backend.example.com/instances/myinst/private/instances
 
 --------------
@@ -853,6 +852,7 @@ Setting up instances
 .. http:post:: /private/instances
 
   This request will be used to create a new merchant instance in the backend.
+  It is only available at the implicit default instance.
 
   **Request:**
 
@@ -918,7 +918,7 @@ Setting up instances
     }
 
 
-.. http:post:: /private/instances/$INSTANCE/auth
+.. http:post:: [/instances/$INSTANCE]/private/auth
 
    Update the authentication settings for an instance.
 
@@ -950,7 +950,7 @@ Setting up instances
     }
 
 
-.. http:patch:: /private/instances/$INSTANCE
+.. http:patch:: [/instances/$INSTANCE]/private
 
   Update the configuration of a merchant instance.  PATCH operations against
   an instance are authenticated by checking that an authorization is provided
@@ -1019,7 +1019,9 @@ Inspecting instances
 .. _instances:
 .. http:get:: /private/instances
 
-  This is used to return the list of all the merchant instances
+  This is used to return the list of all the merchant instances.
+  It is only available at the implicit default instance.
+
 
   **Response:**
 
@@ -1058,7 +1060,7 @@ Inspecting instances
    }
 
 
-.. http:get:: /private/instances/$INSTANCE
+.. http:get:: [/instances/$INSTANCE]/private
 
   This is used to query a specific merchant instance.
 
@@ -1140,7 +1142,7 @@ Inspecting instances
 Deleting instances
 ------------------
 
-.. http:delete:: /private/instances/$INSTANCE
+.. http:delete:: [/instances/$INSTANCE]/private
 
   This request will be used to delete (permanently disable)
   or purge merchant instance in the backend. Purging will
@@ -1189,7 +1191,7 @@ management.
 Adding products to the inventory
 --------------------------------
 
-.. http:post:: /private/products
+.. http:post:: [/instances/$INSTANCE]/private/products
 
   This is used to add a product to the inventory.
 
@@ -1250,7 +1252,7 @@ Adding products to the inventory
 
 
 
-.. http:patch:: /private/products/$PRODUCT_ID
+.. http:patch:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
 
   This is used to update product details in the inventory. Note that the
   ``total_stock`` and ``total_lost`` numbers MUST be greater or equal than
@@ -1319,7 +1321,7 @@ Adding products to the inventory
 Inspecting inventory
 --------------------
 
-.. http:get:: /private/products
+.. http:get:: [/instnaces/$INSTANCE]/private/products
 
   This is used to return the list of all items in the inventory.
 
@@ -1347,7 +1349,7 @@ Inspecting inventory
     }
 
 
-.. http:get:: /private/products/$PRODUCT_ID
+.. http:get:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
 
   This is used to obtain detailed information about a product in the inventory.
 
@@ -1407,7 +1409,7 @@ Inspecting inventory
 Reserving inventory
 -------------------
 
-.. http:post:: /private/products/$PRODUCT_ID/lock
+.. http:post:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock
 
   This is used to lock a certain quantity of the product for a limited
   duration while the customer assembles a complete order.  Note that
@@ -1464,7 +1466,7 @@ Reserving inventory
 Removing products from inventory
 --------------------------------
 
-.. http:delete:: /private/products/$PRODUCT_ID
+.. http:delete:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
 
   Delete information about a product.  Fails if the product is locked by
   anyone.
@@ -1494,7 +1496,7 @@ Creating orders
 
 .. _post-order:
 
-.. http:post:: /private/orders
+.. http:post:: [/instances/$INSTANCE]/private/orders
 
   Create a new order that a customer can pay for.
 
@@ -1657,7 +1659,7 @@ Creating orders
 Inspecting orders
 -----------------
 
-.. http:get:: /private/orders
+.. http:get:: [/instances/$INSTANCE]/private/orders
 
   Returns known orders up to some point in the past.
 
@@ -1714,7 +1716,7 @@ Inspecting orders
       paid: boolean;
     }
 
-.. http:get:: /private/orders/$ORDER_ID
+.. http:get:: [/instances/$INSTANCE]/private/orders/$ORDER_ID
 
   Merchant checks the payment status of an order.  If the order exists but is not paid
   and not claimed yet, the response provides a redirect URL.  When the user goes to this URL,
@@ -1898,7 +1900,7 @@ later tell the backend to forget those details (without changing the hash of
 the contract!) to minimize risks from information leakage.
 
 
-.. http:patch:: /private/orders/$ORDER_ID/forget
+.. http:patch:: [/instances/$INSTANCE]/private/orders/$ORDER_ID/forget
 
   Forget fields in an order's contract terms that the merchant no
   longer needs.
@@ -1945,7 +1947,7 @@ the contract!) to minimize risks from information leakage.
     }
 
 
-.. http:delete:: /private/orders/$ORDER_ID
+.. http:delete:: [/instances/$INSTANCE]/private/orders/$ORDER_ID
 
   Delete information about an order.  Fails if the order was paid in the
   last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was
@@ -1967,7 +1969,7 @@ the contract!) to minimize risks from information leakage.
 Giving Refunds
 --------------
 
-.. http:post:: /private/orders/$ORDER_ID/refund
+.. http:post:: [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund
 
   Increase the refund amount associated with a given order.  The user should be
   redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet.
@@ -2028,7 +2030,7 @@ exchange failed to perform a wire transfer that was due.
 Informing the backend about incoming wire transfers
 ---------------------------------------------------
 
-.. http:post:: /private/transfers
+.. http:post:: [/instances/$INSTANCE]/private/transfers
 
   Inform the backend over an incoming wire transfer. The backend should inquire about the details with the exchange and mark the respective orders as wired.  Note that the request will fail if the WTID is not unique (which should be guaranteed by a correct exchange).
   This request is idempotent and should also be used to merely re-fetch the
@@ -2254,7 +2256,7 @@ Informing the backend about incoming wire transfers
 Querying known wire transfers
 -----------------------------
 
-.. http:get:: /private/transfers
+.. http:get:: [/instances/$INSTANCE]/private/transfers
 
   Obtain a list of all wire transfers the backend has checked.  Note that when
   filtering by timestamp (using "before" and/or "after"), we use the time
@@ -2354,7 +2356,7 @@ transfer subject when wiring the tipping campaign
 funds to the exchange.
 
 .. _tips:
-.. http:post:: /private/reserves
+.. http:post:: [/instances/$INSTANCE]/private/reserves
 
   Create a reserve for tipping.
 
@@ -2406,7 +2408,7 @@ funds to the exchange.
       payto_uri: string;
     }
 
-.. http:get:: /private/reserves
+.. http:get:: [/instances/$INSTANCE]/private/reserves
 
   Obtain list of reserves that have been created for tipping.
 
@@ -2462,7 +2464,7 @@ funds to the exchange.
 Query funds remaining
 ---------------------
 
-.. http:get:: /private/reserves/$RESERVE_PUB
+.. http:get:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB
 
   Obtain information about a specific reserve that have been created for tipping.
 
@@ -2536,7 +2538,7 @@ Query funds remaining
 Authorizing tips
 ----------------
 
-.. http:post:: /private/reserves/$RESERVE_PUB/authorize-tip
+.. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-tip
 
   Authorize creation of a tip from the given reserve.
 
@@ -2585,7 +2587,7 @@ Authorizing tips
     }
 
 
-.. http:post:: /private/tips
+.. http:post:: [/instances/$INSTANCE]/private/tips
 
   Authorize creation of a tip from the given reserve, except with
   automatic selection of a working reserve of the instance by the
@@ -2610,7 +2612,7 @@ Authorizing tips
 Deleting reserves
 -----------------
 
-.. http:delete:: /private/reserves/$RESERVE_PUB
+.. http:delete:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB
 
   Delete information about a reserve.  Fails if the reserve still has
   committed to tips that were not yet picked up and that have not yet
@@ -2635,7 +2637,7 @@ Deleting reserves
 Checking tip status
 -------------------
 
-.. http:get:: /private/tips/$TIP_ID
+.. http:get:: [/instances/$INSTANCE]/private/tips/$TIP_ID
 
   Obtain information about a particular tip.
 
@@ -2687,7 +2689,7 @@ Checking tip status
     }
 
 
-.. http:get:: /private/tips
+.. http:get:: [/instances/$INSTANCES]/private/tips
 
   Return the list of all tips.