[GNUnet-SVN] [taler-api] branch master updated: update merchant backend protocol, talk about repurchase correlation

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository api.

The following commit(s) were added to refs/heads/master by this push:
     new 6b44e31  update merchant backend protocol, talk about repurchase 
correlation
6b44e31 is described below

commit 6b44e31b270848d736b55d18cc4726e6b01f85b4
Author: Florian Dold <address@hidden>
AuthorDate: Tue Mar 7 17:55:28 2017 +0100

    update merchant backend protocol, talk about repurchase correlation
---
 api/api-merchant.rst | 47 +++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/api/api-merchant.rst b/api/api-merchant.rst
index 5b0e71e..a8a54b4 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 n [...]
+    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

-- 
To stop receiving notification emails like this one, please contact
address@hidden