[GNUnet-SVN] [taler-merchant] branch master updated: doc: update

[gnunet]

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

dold pushed a commit to branch master
in repository merchant.

The following commit(s) were added to refs/heads/master by this push:
     new 304e1de  doc: update
304e1de is described below

commit 304e1def724fcdcbfc0be8c752f51317ed8a1d22
Author: Florian Dold <address@hidden>
AuthorDate: Sun Mar 11 16:03:41 2018 +0100

    doc: update
---
 doc/merchant-api.content.texi | 231 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 205 insertions(+), 26 deletions(-)

diff --git a/doc/merchant-api.content.texi b/doc/merchant-api.content.texi
index 0c613b6..031085e 100644
--- a/doc/merchant-api.content.texi
+++ b/doc/merchant-api.content.texi
@@ -55,7 +55,8 @@ Texts.  A copy of the license is included in the section 
entitled
 @menu
 * Introduction::                                  What this tutorial is about
 * Accepting a Simple Payment::                    How to accept simple payments
-* Back-office-integration::                       How to integrate with the 
back office
+* Giving Refunds::                                How to give refunds to 
customers
+* Giving Customer Tips::                          How to reward customers with 
tips
 * Advanced topics::                               Detailed solutions to 
specific issues
 
 
@@ -77,23 +78,20 @@ Indices
 
 @section About GNU Taler
 
-GNU Taler is an open protocol for an electronic payment system with a
-free software reference implementation.  GNU Taler offers secure, fast
-and easy payment processing using well understood cryptographic
-techniques.  GNU Taler allows customers to remain anonymous, while
-ensuring that merchants can be held accountable by governments.
-Hence, GNU Taler is compatible with anti-money-laundering (AML) and
-know-your-customer (KYC) regulation, as well as data protection
-regulation (such as GDPR).
+GNU Taler is an open protocol for an electronic payment system with a free
+software reference implementation.  GNU Taler offers secure, fast and easy
+payment processing using well understood cryptographic techniques.  GNU Taler
+allows customers to remain anonymous, while ensuring that merchants can be held
+accountable by governments.  Hence, GNU Taler is compatible with
+anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as
+data protection regulation (such as GDPR).
 
 
 @section About this tutorial
 
-This tutorial addresses how to integrate GNU Taler with Web shops. It describes
-how to create a Web shop that processes payments with the help of a GNU Taler
-merchant @emph{backend}.  In the second chapter, you will learn how to trigger
-the payment process from the Web site, how to communicate with the backend, how
-to generate a proposal and process the payment.
+This tutorial addresses how to process payments using the GNU Taler merchant
+Backend. This chapter explains some basic concepts.  In the second chapter, you
+will learn how to do basic payments.
 
 @clear GOT_LANG
 @ifset LANG_PYTHON
@@ -172,8 +170,8 @@ in the @code{Authorization} header.  The value of this 
header must be
 @ifset LANG_CURL
 @set GOT_LANG 1
 @example
-$ curl -i 'https://backend.demo.taler.net/' \
-    --header "Authorization: ApiKey sandbox"
+curl -i 'https://backend.demo.taler.net/' \
+  --header "Authorization: ApiKey sandbox"
 # HTTP/1.1 200 OK
 # [...]
 #
@@ -250,7 +248,7 @@ that was purchased.
 @end itemize
 
 After successfully POSTing to @code{/order}, an @code{order_id} will be
-returned.  Together with the @code{instance id}, the order id uniquely
+returned.  Together with the merchant @code{instance}, the order id uniquely
 identifies the order within a merchant backend.
 
 @clear GOT_LANG
@@ -258,15 +256,15 @@ identifies the order within a merchant backend.
 @set GOT_LANG 1
 @example
 @verbatim
-$ ORDER='
+ORDER='
 {"order": {
   "amount": "KUDOS:10",
   "summary": "Donation",
   "fulfillment_url": "https://example.com/thanks.html"}}
 '
 
-$ curl -i -X POST 'https://backend.demo.taler.net/order' \
-    --header "Authorization: ApiKey sandbox" -d "$ORDER"
+curl -i -X POST 'https://backend.demo.taler.net/order' \
+     --header "Authorization: ApiKey sandbox" -d "$ORDER"
 # HTTP/1.1 200 OK
 # [...]
 #
@@ -284,8 +282,8 @@ $ curl -i -X POST 'https://backend.demo.taler.net/order' \
 >>> order = dict(order=dict(amount="KUDOS:10",
 ...                         summary="Donation",
 ...                         fulfillment_url="https://example.com/thanks.html";))
->>> requests.get("https://backend.demo.taler.net";,
-...              headers={"Authorization": "ApiKey sandbox"})
+>>> requests.post("https://backend.demo.taler.net";, data=order,
+...               headers={"Authorization": "ApiKey sandbox"})
 <Response [200]>
 @end verbatim
 @end example
@@ -356,17 +354,189 @@ payment was completed by the user, the response will 
contain the following field
 @item @var{last_session_id}:  Last session ID used by the customer's wallet.  
Advanced feature, explained later.
 @end itemize
 
address@hidden Giving Refunds
address@hidden Giving Refunds
+A refund in GNU Taler is a way to ``undo'' a payment.  It needs to be
+authorized by the merchant at request of the customer.  Refunds can be full
+refunds, or only refund a fraction of the original amount paid.  Refunds are
+time-limited and can only happen while the exchange holds funds for a
+particular payment in escrow.  The time during which a refund is possible
+can be controlled by setting the @code{refund_deadline} in an order.  The 
default
+value for the refund deadline depends on the configuration of the backend.
+
+The frontend can instruct the merchant backend to authorize a refund by 
posting to the
address@hidden/refund} endpoint.
+
+The refund request JSON object has the following fields:
address@hidden
address@hidden @var{order_id}: The ID that identifies the order to be refunded.
address@hidden @var{instrance}: The merchant instance to use (defaults to 
@code{default}).
address@hidden @var{refund}:  The amount to be refunded.  If a previous refund 
was
+authorized for the same order, the new amout must be higher.  Indicates the
+total amount refunded, @emph{not} an increase in the refund.
address@hidden @var{reason}:  Reason for the refund, only used for the Back 
Office and not directly shown to the customer.
address@hidden itemize
+
+If the request is successful (indicated by HTTP status code 200), the response
+includes a @code{refund_redirect_url}.  The frontend must navigate the
+customer's browser to allow the refund to be processed by the wallet.
+
+This code snipped illustrates giving a refund:
address@hidden GOT_LANG
address@hidden LANG_CURL
address@hidden GOT_LANG 1
address@hidden
address@hidden
+REFUND_REQ='
+{"order_id": "2018.058.21.46.06-024C85K189H8P",
+ "refund": "KUDOS:10",
+ "reason": "Customer did not like the product"}
+'
+
+curl -i -X POST 'https://backend.demo.taler.net/refund' \
+     --header "Authorization: ApiKey sandbox" -d "$REFUND_REQ"
+# HTTP/1.1 200 OK
+# [...]
+#
+# {
+#   [...]
+#   "refund_redirect_url": "[...]"
+# }
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
address@hidden
address@hidden
+>>> import requests
+>>> refund_req = dict(order_id="2018.058.21.46.06-024C85K189H8P",
+...                   refund="KUDOS:10",
+...                   reason="Customer did not like the product")
+>>> requests.post("https://backend.demo.taler.net/refund";, data=refund_req,
+...              headers={"Authorization": "ApiKey sandbox"})
+<Response [200]>
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden GOT_LANG
address@hidden
+(example not available for this language)
address@hidden example
address@hidden ifclear
+
address@hidden Giving Customer Tips
address@hidden Giving Customer Tips
+GNU Taler allows merchants to give small sums of money directly to the
+customer, for example to incentivize actions such as filling out a survey or
+trying a new feature.  The merchant backend must be properly configured for
+this, and enough funds must be made available for tipping @xref{Top,,, manual,
+Taler Merchant Operating Manual}.
+
+To check if tipping is configured properly and if there are enough funds 
available to tip,
+query the @code{/tip-query} endpoint:
+
address@hidden GOT_LANG
address@hidden LANG_CURL
address@hidden GOT_LANG 1
address@hidden
address@hidden
+curl -i 'https://backend.demo.taler.net/tip-query?instance=default' --header 
"Authorization: ApiKey sandbox"
+# HTTP/1.1 200 OK
+# [...]
+#
+# {
+#  [...]
+#  "amount_available": "KUDOS:153.47",
+#  "amount_authorized": "KUDOS:10"
+# }
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
address@hidden
address@hidden
+>>> import requests
+>>> requests.get("https://backend.demo.taler.net";,
+...              headers={"Authorization": "ApiKey sandbox"})
+<Response [200]>
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden GOT_LANG
address@hidden
+(example not available for this language)
address@hidden example
address@hidden ifclear
+
+To authorize a tip, post to @code{/tip-authorize}.  The following fields are 
recognized in the JSON
+request object:
address@hidden
address@hidden @var{amount}: Amount that should be given to the customer as a 
tip.
address@hidden @var{instance}: Merchant instance that gives the tip (each 
instance has
+their own independend tipping funds configured).
address@hidden @var{justification}: Description of why the tip was given.  Not 
given to the customer, but
+used from back office purposes.
address@hidden @var{next_url}: The URL that the user's browser will be 
redirected to by the wallet, once
+the tip has been processed.
address@hidden itemize
+
+The response contains a @code{tip_redirect_url}, the customer's browser must be
+redirected to this URL to accept the tip.
+
+This code snipped illustrates giving a tip:
address@hidden GOT_LANG
address@hidden LANG_CURL
address@hidden GOT_LANG 1
address@hidden
address@hidden
+TIP_REQ='
+{"amount: "KUDOS:0.5",
+ "instance": "default",
+ "justification": "User filled out survey"}
+'
+
+curl -i -X POST 'https://backend.demo.taler.net/tip-authorize' \
+     --header "Authorization: ApiKey sandbox" -d "$TIP_REQ"
+# HTTP/1.1 200 OK
+# [...]
+#
+# {
+#   [...]
+#   "tip_redirect_url": "[...]"
+# }
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
address@hidden
address@hidden
+>>> import requests
+>>> tip_req = dict(amount="KUDOS:0.5",
+...                instance="default",
+...                justification="User filled out survey")
+>>> requests.post("https://backend.demo.taler.net/refund";, data=tip_req,
+...              headers={"Authorization": "ApiKey sandbox"})
+<Response [200]>
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden GOT_LANG
address@hidden
+(example not available for this language)
address@hidden example
address@hidden ifclear
 
address@hidden Back-office-integration
address@hidden Integration with the back office
-Taler ships the back-office feature as a stand-alone Web application.
-See how to run it, on its own documentaion: 
@url{https://docs.taler.net/backoffice/html/manual.html}.
 
 @node Advanced topics
 @chapter Advanced topics
 
 @menu
 * Detecting the Presence of the Taler Wallet::  Detecting the Presence of the 
Taler Wallet
+* Integration with the Back Office::            Integration with the Back 
Office
+* Session-Bound Payments::                      Session-bound payments for 
digital goods
 * The Taler Order Format::                      The Taler Order Format
 @end menu
 
@@ -447,6 +617,15 @@ Note that the registered callbacks can be called more than 
once, since a user
 can disable/enable the wallet in the browser's setting while a shop frontend
 page is open.
 
address@hidden Integration with the Back Office
address@hidden Integration with the Back Office
+Taler ships the back-office feature as a stand-alone Web application.
+See how to run it, on its own documentaion: 
@url{https://docs.taler.net/backoffice/html/manual.html}.
+
address@hidden Session-Bound Payments
address@hidden Session-Bound Payments
+TODO
+
 @c Section describing the format of Taler contracts/proposals in detail
 
 @node The Taler Order Format

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