simplified tipping

1 files changed, 21 insertions, 36 deletions

diff --git a/doc/manual.texi b/doc/manual.texi
index 731b2193..3c7c3c07 100644
--- a/doc/manual.texi
+++ b/doc/manual.texi
@@ -1159,36 +1159,28 @@ each time after you wire more funds to the reserve.
 
 @subsection Authorize a tip
 
-When your front end has reached the point where a client is supposed
+When your frontend has reached the point where a client is supposed
 to receive a tip, it needs to first authorize the tip. For this,
 the frontend must use the ``/tip-authorize'' API of the backend.
-To authorize a tip, the frontend has to provide the amount to
-authorize, the name of the instance, and a justification.  The
-justification is just a string that is stored in the database with
-the transaction.  It is not meaningful for Taler.
-
-In response to this triplet, the backend will return a tip identifier,
-an expiration time and the exchange URI.  The expiration time will
-indicate how long the tip is valid (when the reserve expires).  The
-tip identifier allows the client's wallet to pick up the tip.  The
-frontend must now send the tip identifier, expiration time, EXCHANGE
-URI and the total amount to the browser in a special ``402 Payment Required''
-response with the following headers:
+To authorize a tip, the frontend has to provide the following information
+in the body of the POST request:
 
-@example
-X-Taler-Tipping-Url: PICKUP URL with tip ID
-X-Taler-Tipping-Exchange: EXCHANGE URL
-X-Taler-Tipping-Amount: AMOUNT
-X-Taler-Tipping-Deadline: EXPIRATION
-@end example
+@itemize @bullet
+@item The amount of the tip
 
-The first header line must include a Web URL for picking up the tip.
-It should include the tip ID (or at least some information that the
-frontend can use to lookup the tip ID).  For example, it might be
-``https://shop/tip-pickup?tip_id=ID'' where ``ID'' is the tip ID
-that was returned from the backend.  Finally, the frontend must
-implement this ``/tip-pickup'' handler, as described in the next
-section.
+@item The justification (only used internally for the back-office)
+
+@item The URL where the wallet should navigate next after the tip was processed
+
+@item The tip-pickup URL (see next section)
+@end itemize
+
+In response to this request, the backend will return a tip token, an expiration
+time and the exchange URI.  The expiration time will indicate how long the tip
+is valid (when the reserve expires).  The tip token is an opaque string that
+contains all the information needed by the wallet to process the tip.  The
+frontend must send this tip token to the browser in a  a special ``402 Payment
+Required'' response inside the @code{X-Taler-Tip} header.
 
 The frontend should handle errors returned by the backend, such
 as missconfigured instances or a lack of remaining funds for tipping.
@@ -1196,16 +1188,9 @@ as missconfigured instances or a lack of remaining funds for tipping.
 
 @subsection Picking up of the tip
 
-The wallet will POST a JSON object with a single member ``planchets''
-to the shop's ``/tip-pickup'' handler.  The frontend must then add the
-``tip_id'' field to this JSON body and forward it to the
-``/tip-pickup'' handler of the backend.  The response generated by the
-backend can then be forwarded directly to the wallet.  However, the
-frontend may want to add a field ``next_url'' to provide a suggestion
-as to where the wallet should navigate after picking up the tip.  A
-common value for ``next_url'' would be the home page of the shop.
-
-@c FIXME: document ``next_url'' somewhere in the API specs?
+The wallet will POST a JSON object to the shop's ``/tip-pickup'' handler.  The
+frontend must then forward this request to the backend.  The response
+generated by the backend can then be forwarded directly to the wallet.
 
 
 @c **********************************************************