[GNUnet-SVN] [taler-merchant-frontend-examples] branch master updated: clean up documentation on tipping

[gnunet]

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

grothoff pushed a commit to branch master
in repository merchant-frontend-examples.

The following commit(s) were added to refs/heads/master by this push:
     new 7ebeb18  clean up documentation on tipping
7ebeb18 is described below

commit 7ebeb1872014ced9ec27e568fae93a928fcc7312
Author: Christian Grothoff <address@hidden>
AuthorDate: Sun Oct 15 17:36:27 2017 +0200

    clean up documentation on tipping
---
 common/texi/api-reference.texi | 81 ++++++++++++++++++++++++++++++++----------
 1 file 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
address@hidden 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:
address@hidden @code
address@hidden 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:
+
address@hidden
+* Payment::                 Payment
+* Refund::                  Refund
+* Tipping::                 Tipping
address@hidden menu
 
address@hidden Payment
address@hidden Payment
address@hidden 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:
+
address@hidden @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.
address@hidden table
+
+
address@hidden Refund
address@hidden Refund
address@hidden refund
 
address@hidden 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.
address@hidden refund deadline
 
address@hidden 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:
 
address@hidden X-Taler-User-Tipping-Amount
address@hidden @code
address@hidden 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.
address@hidden table
+
+
address@hidden Tipping
address@hidden Tipping
address@hidden tipping
+
+The following headers for @code{402 Payment Required} are involved in
+tipping clients:
+
address@hidden @code
address@hidden 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 [...]
+
address@hidden X-Taler-Tipping-Exchange
+Exchange base URL for the exchange that the merchant will allow the client to 
withdraw the tip from.
+
address@hidden X-Taler-Tipping-Amount
 Amount of tip that the user is receiving, in the standard amount format 
(CURR:X.Y).
 
address@hidden 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
 

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