improve user guide, deduplicate with merchant backend manual

1 files changed, 199 insertions, 7 deletions

diff --git a/taler-user-guide.rst b/taler-user-guide.rst
index 6f7e7890..6284426e 100644
--- a/taler-user-guide.rst
+++ b/taler-user-guide.rst
@@ -129,6 +129,48 @@ to undergo some KYC check before the funds are actually released to the
 receiver.
 
 
+.. index:: instance
+.. _Instance-account-configuration:
+
+Configuring Accounts at a Merchant Instance
+===========================================
+
+Before you can setup a merchant instance, you need somebody to operate a
+`Taler Merchant Backend <taler-merchant-backend-operator-manual>`_ and `grant
+you access to an instance <Instance-setup>`_ at that backend.  For this, you
+should receive the base URL of the instance and an access token.
+
+The main configuration data that must be provided for each instance
+is the bank account information.
+
+In order to receive payments, the merchant backend needs to
+communicate bank account details to the exchange.
+
+The bank account information is provided in the form of a ``payto://``-URI.
+See `RFC 8905 <https://tools.ietf.org/html/rfc8905>`_
+for the format of ``payto://``-URIs.  Note that the "receiver-name" is
+optional in RFC 8905 but mandatory in GNU Taler.
+
+For first tests, you may want to sign up for a KUDOS bank account at
+`https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.  In this case,
+the ``payto://``-URI will be of the form
+``payto://iban/$IBAN?receiver-name=$NAME`` where ``$IBAN`` must be replaced
+with the IBAN shown on the main page of the account shown at
+`https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_ after logging
+in.
+
+When deploying Taler with the real banking system, you primarily need to
+change the currency of the configuration from KUDOS to the actual currency
+(such as EUR, USD, CHF) and provide a ``payto://``-URI of your actual bank
+account. In Europe, this will involve knowing your IBAN number. If you have an
+IBAN, the corresponding ``payto://``-URI is simply
+``payto://iban/$IBAN?receiver-name=$NAME`` where ``$IBAN`` must be replaced
+with the actual IBAN number and ``$NAME`` with your actual name. Make sure to
+URI-encode your name.  The merchant SPA will do this automatically when you
+use it to configure the bank account.
+
+
+
 Using the Point-of-Sale App
 ===========================
 
@@ -232,13 +274,163 @@ display a confirmation code that can be shown to the merchant as a proof of
 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.
+To receive notifications when a purchase has been made or a refund was given
+to a wallet, you can set up webhooks in the GNU Taler merchant backend.
+Webhooks allow you to trigger HTTP(S) requests based on certain events.  A
+webhook is thus simply an HTTP request that the GNU Taler merchant backend
+will make when a certain event (such as 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.
+
+Webhooks are configured per instance.  In the Webhook configuration,
+you can specify which URL, which HTTP headers, which HTTP method and what HTTP
+body to send to the Webhook.  Webhooks are automatically retried (with
+increasing delays) when the target server returns a temporary error.
+
+Mustach templates are used when defining the contents of Webhooks.  Depending
+on the triggering event, the templates will be expanded with event-specific
+data.
+
+Pay events
+^^^^^^^^^^
+
+For "pay" events, the backend will provide the following
+information to the Mustach templating engine:
+
+  * contract_terms: the contract terms of the paid order
+  * order_id: the ID of the order that received the refund
+
+
+Refund events
+^^^^^^^^^^^^^
+
+For "refund" events, the backend will provide the following information to the
+Mustach templating engine:
+
+  * timestamp: time of the refund (in nanoseconds since 1970)
+  * order_id: the ID of the order that received the refund
+  * contract_terms: the full JSON of the contract terms of the refunded order
+  * refund_amout: the amount that was being refunded
+  * reason: the reason entered by the merchant staff for granting the refund;
+    be careful, you probably want to inform your staff if a webhook may expose
+    this information to the consumer
+
+
+
+
+.. _Tipping-visitors:
+
+Tipping visitors
+================
+
+.. index:: tipping
+
+Taler can also be used to tip Web site visitors. For example, you may be
+running an online survey, and you want to reward those people that have
+dutifully completed the survey. If they have installed a Taler wallet,
+you can provide them with a tip for their deeds. This section describes
+how to setup the Taler merchant backend for tipping.
+
+There are three basic steps that must happen to tip a visitor.
+
+.. _Fund-the-reserve:
+
+Fund the reserve
+----------------
+
+.. index:: reserve
+
+First, the reserve must be setup in the merchant backend. A reserve
+is always tied to a particular instance. To create a reserve with
+10 KUDOS at instance ``default`` using the demo exchange, use:
+
+.. code-block:: console
+
+   $ taler-merchant-setup-reserve \
+       -a KUDOS:10 \
+       -e https://exchange.demo.taler.net/ \
+       -m http://localhost:8888/instances/default
+
+The above command assumes that the merchant runs on localhost on
+port 8888.
+For more information, including how to transmit authentication information
+to the backend, see :doc:`manpages/taler-merchant-setup-reserve.1`.
+
+The command will output a ``payto://`` URI which specifies where to
+wire the funds and which wire transfer subject to use.
+
+  .. note::
+
+     FIXME: add full example output.
+
+In our example, the output for the wire transfer subject is:
+
+.. code-block:: none
+
+   QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
+
+You now need to make a wire transfer to the exchange’s bank account
+using the given wire transfer subject.
+
+Make your wire transfer and (optionally) check at
+“https://exchange/reserves/QPE24X...” whether your transfer has arrived at the
+exchange.
+
+Once the funds have arrived, you can start to use the reserve for
+tipping.
+
+Note that an exchange will typically close a reserve after four weeks, wiring
+all remaining funds back to the sender’s account. Thus, you should plan to
+wire funds corresponding to a campaign of about two weeks to the exchange
+initially. If your campaign runs longer, you should setup another reserve
+every other week to ensure one is always ready.
+
+.. _Authorize-a-tip:
+
+Authorize a tip
+---------------
+
+When your frontend has reached the point where a client is supposed to receive
+a tip, it needs to first authorize the tip. For this, the frontend must use
+a POST to ``/private/reserves/$RESERVE_PUB/authorize-tip``. To authorize a
+tip, the frontend has to provide the following information in the body of the
+POST request:
+
+-  The amount of the tip
+
+-  The justification (only used internally for the back-office)
+
+-  The URL where the wallet should navigate next after the tip was
+   processed
+
+-  The tip-pickup URL (see next section)
+
+In response to this request, the backend will return a tip token, an
+expiration time and the exchange URL. The expiration time will indicate
+how long the tip is valid (when the reserve expires). The tip token is
+an opaque string that contains all the information needed by the wallet
+to process the tip. The frontend must send this tip token to the browser
+in a special “402 Payment Required” response inside the ``X-Taler-Tip``
+header.
+
+The frontend should handle errors returned by the backend, such as
+misconfigured instances or a lack of remaining funds for tipping.
+
+.. _Picking-up-of-the-tip:
+
+Picking up of the tip
+---------------------
+
+The wallet will POST a JSON object to the shop’s
+``/tips/$TIP_ID/pickup`` handler.
+The frontend must then forward this request to the backend. The response
+generated by the backend can then be forwarded directly to the wallet.
+
+