clean up documentation on tipping

1 files changed, 63 insertions, 18 deletions

diff --git a/common/texi/api-reference.texi b/common/texi/api-reference.texi
index 6e3cd52..1a90e96 100644
--- a/common/texi/api-reference.texi
+++ b/common/texi/api-reference.texi
@@ -9,19 +9,32 @@
 
 @node Headers for HTTP 402
 @section Headers for HTTP 402
+
 The HTTP status code @code{402 Payment Required} can be used by the merchant
-frontend to trigger operations related to payments in the user agent.  The user
-agent associates at most one proposal with every URL via the proposal's
-@code{fulfillment_url} field.  The associated proposal is either missing (in
-case it doesn't exist), paid (in case the payment for it was successfully sent
-to the merchant) or unpaid.  If the associated proposal is unpaid,  @code{402
-Payment Required} will cause the user agent to pay for the associated proposal.
-
-The following headers for @code{402 Payment Required} are recognized by Taler and further influence the processing:
-@table @code
-@item X-Taler-Refund-Url
-If this header present, the value of this header must be a URL that the user agent can use to request and process refunds.
+frontend to trigger operations related to payments in the user agent.  There
+are three different types of possible interactions:
+
+@menu
+* Payment::                 Payment
+* Refund::                  Refund
+* Tipping::                 Tipping
+@end menu
 
+@node Payment
+@subsection Payment
+@cindex payment
+
+For payments, the user agent associates at most one proposal with every URL via the
+proposal's @code{fulfillment_url} field.  The associated proposal is
+either missing (in case it does not exist), paid (in case the payment
+for it was successfully sent to the merchant) or unpaid.  If the
+associated proposal is unpaid, @code{402 Payment Required} will cause
+the user agent to pay for the associated proposal.
+
+The following headers for @code{402 Payment Required} are involved in
+processing payments:
+
+@table @code
 @item X-Taler-Contract-Url
 If there is no associated proposal, the user agent will fetch a proposal from
 this URL and process it.  This typically prompts the user to agree to pay.
@@ -29,20 +42,52 @@ this URL and process it.  This typically prompts the user to agree to pay.
 @item X-Taler-Offer-Url
 If there is no associated proposal and @code{X-Taler-Contract-Url} is not
 specified, the browser will navigate to this URL.
+@end table
+
+
+@node Refund
+@subsection Refund
+@cindex refund
 
-@item X-Taler-User-Tipping-Url
-If this header present, the value of this header must be a URL that the user agent can use to obtain tips (small, non-binding
-financial rewards) payed from the merchant to the user's wallet.  If this field is present, @code{X-Taler-User-Tipping-Exchange}
-and @code{X-Taler-User-Tipping-Amount} must also be present.
+A merchant can give a customer a refund, for example if they are unable
+to deliver the goods or if the goods turned out to be defective.  Refunds
+can only be issued before the exchange has transferred the funds to the
+customer as per the @code{refund_deadline} of the contract.
+@cindex refund deadline
 
-@item X-Taler-User-Tipping-Exchange
-Exchange base URL for the exchange that the merchant helps withdrawing the tip from.
+The following headers for @code{402 Payment Required} are involved in
+processing refunds:
 
-@item X-Taler-User-Tipping-Amount
+@table @code
+@item X-Taler-Refund-Url
+If this header present, the value of this header must be a URL that the user agent can use to request and process refunds.
+@end table
+
+
+@node Tipping
+@subsection Tipping
+@cindex tipping
+
+The following headers for @code{402 Payment Required} are involved in
+tipping clients:
+
+@table @code
+@item X-Taler-Tipping-Url
+If this header present, the value of this header must be a URL that the user agent can use to obtain tips (small, non-binding financial rewards) payed from the merchant to the user's wallet.  If this field is present, @code{X-Taler-Tipping-Exchange} and @code{X-Taler-Tipping-Amount} must also be present.  The wallet will then generate appropriate planchets and POST the required information in JSON to this URL.  The merchant should add the @code{tip_id} and @code{instance} fields and pass the POSTed @code{planchets} to its backend at the @code{/tip-pickup} URI. The wallet will expect a response in the same format as returned by the backend.  Note that the tipping URL will typically need to encode the @code{tip_id} returned by the @code{/tip-authorize} function of the merchant's backend.
+
+@item X-Taler-Tipping-Exchange
+Exchange base URL for the exchange that the merchant will allow the client to withdraw the tip from.
+
+@item X-Taler-Tipping-Amount
 Amount of tip that the user is receiving, in the standard amount format (CURR:X.Y).
 
+@item X-Taler-Tipping-Deadline
+Optional deadline (in the usual HTTP ``Date'' format) until which the tip is available. Later requests may be rejected by the merchant.  Note that the absence of this field should not be understood to imply that the offer is valid indefinitely. However, if there is a deadline, the wallet may visually indicate to the user that the tip needs to be picked up in a timely fashion (assuming the wallet interactively asks for confirmation and the deadline is near).
+
 @end table
 
+
+
 @node JavaScript API
 @section JavaScript API