commit 59cd3450714361b392662118e2a29df92c472b09
parent a58a34734f253382c3f8c346682a88a8e7ae2dae
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 14 Apr 2023 11:24:55 +0200
expand guide
Diffstat:
| M | taler-user-guide.rst | | | 79 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- |
1 file changed, 74 insertions(+), 5 deletions(-)
diff --git a/taler-user-guide.rst b/taler-user-guide.rst
@@ -102,10 +102,49 @@ receiver.
Using the Point-of-Sale App
===========================
+A simple way for merchants to accept GNU Taler payments is the use of the
+point-of-sale app. The app can be installed on an Android phone or tablet
+and is configured via a simple JSON file on a Web site:
+
+ * In the app settings you need to specify the URL of the Web site where
+ the app can download the categories, products and prices from which
+ orders are to be compiled. You can optionally specify a username and
+ password to authenticate to the Web server.
+
+ * The syntax of the JSON file is described in the point-of-sale app
+ manual. However, you may simply want to download the sample JSON
+ file from our documentation and use it as a starting point.
+
+ * A key option is the merchant backend with the authorization key
+ which must be included in this JSON configuration. You may point
+ the point-of-sale app to any instance of a merchant backend.
+
+Once configured, the point-of-sale app allows the user to select a product
+category and then to quickly add products from that category to an order. You
+can easily edit the order, and finally use the "complete" button to generate a
+QR code. The QR code must then be scanned by the GNU Taler wallet to initiate
+the payment. Multiple orders can be entered concurrently, for example in a
+restaurant where multiple tables are waited on at the same time.
+
Setting up an order in the merchant backoffice SPA
==================================================
+Arbitrary orders can also be created manually using the Web interface of
+the GNU Taler merchant backend. For this, log into the single page app (SPA)
+of the merchant backend using the authorization token of the respective
+instance you want to use.
+
+You can then set up orders by providing all of the required fields of an
+order, in particular an order summary and a price. You can also set various
+optional fields or override instance default settings.
+
+When the order has been setup, you can follow a link to the payment page
+which will show the QR code (and/or URL) that a GNU Taler wallet would need
+to receive to initiate the payment process. The order status page also
+shows you the progress of the order, including when a wallet has made the
+payment. You can also use the backend to approve refunds.
+
Paying an order
===============
@@ -122,6 +161,34 @@ or directly view the digital product that they purchased.
Setting up a template
=====================
+A template provides all or part of the information needed to setup an order
+and allows GNU Taler wallets to create an order. Usually, the creation of
+orders is a privileged process that requires knowledge of the authorization
+code for the respective instance. With templates, a customer's wallet can
+directly create an order on-demand. The information of a template can be
+partial, in which case the customer is expected to provide the remaining
+details, typically the summary and/or amount of the order.
+
+When setting up a template you need to specify all of the fixed inputs that
+the customer cannot change. You can then generate a template QR code where
+you may additionally specify editable defaults for the order, such as a
+default summary or a default amount which may still be changed by the wallet.
+The resulting template QR code encodes the specific merchant backend, instance
+and template ID as well as the (editable) default values. The resulting
+static QR code can then be printed and put on display.
+
+Customers can scan the QR code with their GNU Taler wallet, complete the
+missing details or edit the defaults (if any), and pay the resulting order.
+
+To secure template-based payments, you may specify a TOTP secret as part of
+the template. In this case, the merchant backend will send a set of TOTP
+payment confirmation codes to the GNU Taler wallet upon receiving a payment
+for an order created based on the template. If the point-of-sale has a TOTP
+generator with the same secret, they can compare their TOTP code with the
+codes shown by the customer on their wallet. This provides additional
+assurance that the customer actually made the payment instead of just showing
+a fake confirmation screen.
+
Paying with static QR codes
===========================
@@ -138,8 +205,10 @@ payment.
Setting up a webhook
====================
-
-
-
-
-
+To receive notifications when a purchase has been made, you can set up
+webhooks in the GNU Taler merchant backend. A webhook is simply an HTTP
+request that the GNU Taler merchant backend will make when a certain event
+(usually a payment) happens. There are various providers that can send an SMS
+to a phone number based on an HTTP request. Thus, by configuring such a
+provider in a webhook you can receive an SMS notification whenever a customer
+makes a payment at a particular instance.
