From 2a0a13aa815c21426c09175a704277d7e43818a1 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 11 Dec 2017 18:01:45 +0100 Subject: simplified tipping --- doc/manual.texi | 57 +++++++++++++++++++++------------------------------------ 1 file changed, 21 insertions(+), 36 deletions(-) (limited to 'doc') 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 ********************************************************** -- cgit v1.2.3