[taler-docs] branch master updated (f8fbc74 -> 5d64658)

[gnunet]

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

ttn pushed a change to branch master
in repository docs.

    from f8fbc74  fix typo: s/False/false/
     new 3bb8e8c  rewrite claim token details per CG feedback
     new 5d64658  rewrite "auto-refund period" details per CG feedback

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 taler-mcig.rst | 48 ++++++++++++++++++------------------------------
 1 file changed, 18 insertions(+), 30 deletions(-)

diff --git a/taler-mcig.rst b/taler-mcig.rst
index 5c8f918..134970b 100644
--- a/taler-mcig.rst
+++ b/taler-mcig.rst
@@ -190,27 +190,17 @@ are demonstrated in the next section.
 
 **claim token**
   The claim token is a sort of handle on the order and its payment.
-  With it, the customer can access the fulfillment URI from a different
-  device than the one where the wallet is installed.
-  FIXME: that is not the point. The point is that even if the
-  $ORDER_ID can be guessed, the claim token cannot. Thus, a
-  merchant can prevent a third party from claiming an order
-  (by guessing the order ID). Imagine selling concert tickets,
-  and your order IDs are 1,2,3,4,5,. I could try to hijack other
-  visitor's orders (before they have a chance to claim them),
-  using a claim token prevents this.
+  It is useful when the order ID is easily guessable
+  (e.g. incrementing serial number),
+  to prevent one customer hijacking the order of another.
+  On the other hand, even if the order ID is not easily guessable,
+  if you don't care about order theft (e.g. infinite supply, digital goods)
+  and you wish to reduce the required processing (e.g. smaller QR code),
+  you can safely disable the claim token.
 
   By default, Taler creates a claim token for each order.
   To disable this, you can specify ``create_token`` to be ``false``
   in :http:post:`[/instances/$INSTANCE]/private/orders`.
-  => needs guideance as to when to do this, i.e. when
-     there is no worry about people 'stealing' orders
-     compiled by others, either because the order ID is
-     high-entropy OR [[because there is an infinite supply
-     and we are not concerned about order-theft attacks
-     (say by a competitor trying to prevent legitimate
-      customers from claiming their orders) AND want the
-     QR code to get smaller / scan more easily.]]
 
 **refund deadline**
   The refund deadline specifies the time after which you will prohibit
@@ -227,19 +217,17 @@ are demonstrated in the next section.
 **auto-refund period**
   The Taler protocol can automatically offer refunds to the customer's
   wallet without their explicit prompting during the auto-refund period.
-  FIXME: When is this useful?
-
-  FIXME: Is this the same as the refund deadline?
-
-  FIXME: API call?
-  This is useful if it is impossible to notify the customer
-  about a refund. Example is the Snack machine, where a failure
-  to dispense a product triggers a refund, but the snack machine
-  has no good way to tell the shopper that it has issued a refund.
-  So here, the wallet will _watch_ for say 5 minutes for an auto-refund,
-  which is automatically issued by the snack machine (if the optical
-  barrier detects that it could not dispense the product) and appears in the
-  wallet without the buyer needing to take any action.
+
+  This is useful in the case where the purchase cannot be fulfilled
+  (e.g. jammed vending machine), but there is no way to notify the
+  customer about a refund.
+
+  If specified, the customer's wallet will wait that long after
+  authorization (and before fulfillment) before automatically
+  receiving a refund.
+
+  To set the auto-refund period, specify ``auto_refund``
+  in :http:post:`[/instances/$INSTANCE]/private/orders`.
 
 **repurchase detection / prevention**
   Taler can detect a repurchase attempt and prevent it from going through.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.