update merchant backend protocol, talk about repurchase correlation

1 files changed, 31 insertions, 16 deletions

diff --git a/api/api-merchant.rst b/api/api-merchant.rst
index 5b0e71e9..a8a54b45 100644
--- a/api/api-merchant.rst
+++ b/api/api-merchant.rst
@@ -114,12 +114,19 @@ The Frontend HTTP API
 
 .. http:post:: fulfillment_url
 
-  Every fulfillment URL accounts for one purchase.  If the user buys three movies
-  and one e-book, then the fulfillment URL will be such that for the merchant is
-  possible to understand that the user wants those three movies and that e-book.
+  URL that shows the product after it has been purchased.  Going to the a fulfillment URL
+  before the payment was completed must trigger the payment process.
 
-  It is also possible for the user to bookmark the fulfillment URL, so that he/she
-  can replay the purchase and get the same items again in the future.
+  For products that are intended to be purchased only once (such as online news
+  articles), the fulfillment URL should map one-to-one to an article, so that
+  when the user visits the page after they cleared their cookies, the purchase
+  can be replayed.
+
+  For purchases that can be repeated, the fulfillment URL map one-to-one to
+  a proposal, e.g. by including the order id.
+
+  Following these rules allows sharing of links and bookmarking to work correctly,
+  and produces nicely looking semantic URLs.
 
   .. note::
     By "replaying" a payment, we mean that the user reuses the same coins he
@@ -133,24 +140,26 @@ The Merchant Backend HTTP API
 
 The following API are made available by the merchant's `backend` to the merchant's `frontend`.
 
-.. http:post:: /contract/propose
+.. http:post:: /proposal
 
-  Ask the backend to complete and sign an offer to create a proposal.
+  Generate a new proposal, based on the `order` given in the request.  This request is idempotent.
 
   **Request:**
 
-.. _offer:
+.. _proposal:
 
-  The backend expects a `sketch` as input.  The sketch is an :ref:`Offer`_
-  object **missing** the fields:
+  The backend expects an `order` as input.  The sketch is an :ref:`ProposalData`_
+  object **without** the fields:
 
   * `exchanges`
   * `auditors`
   * `H_wire`
   * `merchant_pub`
 
-  The frontend may or may not provide a `instance` field in the sketch, depending on its logic.
-  The ``default`` instance will be used if no `instance` field is found by the backend.
+  The following fields from :ref:`ProposalData`_ are optional and will be filled
+  in by the backend if not present:
+
+  * `merchant.instance` (default instance will be used)
 
   **Response**
 
@@ -158,7 +167,7 @@ The following API are made available by the merchant's `backend` to the merchant
     The backend has successfully created the proposal.  It responds with a :ref:`proposal <proposal>`. 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 proposal 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 never use the same transaction ID.
+    The frontend used the same order ID with different content in the order.
 
 .. http:post:: /pay
 
@@ -198,11 +207,17 @@ The following API are made available by the merchant's `backend` to the merchant
   .. code-block:: tsref
 
     interface PaymentResponse {
-      // Signature of `TALER_PaymentResponsePS`_
-      merchant_sig: EddsaSignature;
+      // Signature on `TALER_PaymentResponsePS`_ with the public
+      // key of the instance in the proposal.
+      sig: EddsaSignature;
 
-      // Contract's hash being signed over
+      // Proposal data hash being signed over
       h_proposal_data: HashCode;
+
+      // Proposal, send for convenience so the frontend
+      // can do order processing without a second lookup on
+      // a successful payment
+      proposal: Proposal;
     }
 
 .. http:get:: /track/transfer