commit 2587e39bb1abed4fd6f427baef354e1332234a33
parent d5ca487760378bb0142785a28676e794a5f52707
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 22 May 2023 22:21:55 +0200
improve user guide, deduplicate with merchant backend manual
Diffstat:
3 files changed, 220 insertions(+), 213 deletions(-)
diff --git a/core/api-bank-merchant.rst b/core/api-bank-merchant.rst
@@ -13,6 +13,8 @@
You should have received a copy of the GNU Affero General Public License along with
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+.. _taler-bank-merchant-http-api:
+
============================
Taler Bank Merchant HTTP API
============================
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -717,6 +717,7 @@ and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`
.. index:: instance
.. _Instance-setup:
+
Instance setup
==============
@@ -747,47 +748,14 @@ times, once for each instance.
:ref:`reverse proxy <reverse-proxy-configuration>`.
-Configuring Accounts
---------------------
-
-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.
-
-
Setup without the Web interface
-------------------------------
-With the knowledge of the ``payto://``-URI, instances can be configured by POSTing
-a request to ``/management/instances`` without using the Web interface.
-This could be useful if you want to create many instances programmatically.
-To create an instance without the Web interface
-create a file ``instance.json`` with an `InstanceConfigurationMessage`
+Instances can be created by POSTing a request to ``/management/instances``
+without using the Web interface. This could be useful if you want to create
+many instances programmatically. To create an instance without the Web
+interface create a file ``instance.json`` with an
+`InstanceConfigurationMessage`:
.. code-block:: json
@@ -806,14 +774,17 @@ create a file ``instance.json`` with an `InstanceConfigurationMessage`
}
In the text above, you must replace ``$PAYTO_URI`` with your actual
-``payto://``-URI. Also, be sure to replace ``KUDOS`` with the fiat currency if the
-setup is for an actual bank. The ``name`` field will be shown as the name of
-your shop. The ``address`` field is expected to contain your shop's physical
-address. The various defaults specify defaults for transaction fees your shop
-is willing to cover, how long offers made to the customer are valid, and how
-long the exchange has before it must wire the funds to your bank
-account. Those defaults can be modified for individual orders.
-For details, see the :ref:`contract terms <contract-terms>` specification.
+``payto://``-URI. You may also leave the account array empty. The instance
+owner must then configure the accounts before the instance becomes usable.
+
+Be sure to replace ``KUDOS`` with the fiat currency if the setup is for an
+actual bank. The ``name`` field will be shown as the name of your shop. The
+``address`` field is expected to contain your shop's physical address. The
+various defaults specify defaults for transaction fees your shop is willing to
+cover, how long offers made to the customer are valid, and how long the
+exchange has before it must wire the funds to your bank account. Those
+defaults can be modified for individual orders. For details, see the
+:ref:`contract terms <contract-terms>` specification.
You can then create the instance using:
@@ -1039,161 +1010,11 @@ REVOKE the database permissions. Finally, restart the merchant services
processes, either via your systemd or init system, or directly.
-.. _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.
-
-
Advanced topics
===============
-.. _Webhooks:
-
-Webhooks
---------
-
-Webhooks allow you to trigger HTTP(S) requests based on certain
-events. 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
-
-
-
.. _MerchantDatabaseScheme:
Database Scheme
@@ -1210,14 +1031,6 @@ The database scheme used by the merchant looks as follows:
.. image:: merchant-db.png
-
-
-Advanced experimental features
-==============================
-
-This section describes features that most merchants will not
-need, or will not need initially.
-
.. _MerchantBenchmarking:
Benchmarking
@@ -1242,7 +1055,7 @@ start.
Benchmark setup
----------------
+^^^^^^^^^^^^^^^
The ``taler-merchant-benchmark`` tool will automatically launch and configure the
exchange, (Python) bank and other tools required for the benchmark. However,
@@ -1271,7 +1084,7 @@ For details, see the :ref:`Exchange Operator Manual <Bank-account>`.
Running the benchmark command
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The tool takes all of the values it needs from the command line, with
one of them being mandatory:
diff --git 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.
+
+
