summaryrefslogtreecommitdiff
path: root/taler-merchant-manual.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-06-25 23:10:17 +0200
committerChristian Grothoff <christian@grothoff.org>2020-06-25 23:10:17 +0200
commite25c00421f555d8fe371b135451f06dedd0e11b5 (patch)
tree5f884c5c7ebb2514ab84df697e09477c18f4fdbf /taler-merchant-manual.rst
parent91a6f971ea9c1bd49195cf24cc34611e9703671e (diff)
downloaddocs-e25c00421f555d8fe371b135451f06dedd0e11b5.tar.gz
docs-e25c00421f555d8fe371b135451f06dedd0e11b5.tar.bz2
docs-e25c00421f555d8fe371b135451f06dedd0e11b5.zip
improving merchant backend documentation
Diffstat (limited to 'taler-merchant-manual.rst')
-rw-r--r--taler-merchant-manual.rst310
1 files changed, 176 insertions, 134 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index d6f07efb..9f44960a 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -673,11 +673,36 @@ uses its own bank accounts and key for signing contracts. It is
mandatory to configure at least the "default" instance.
Instances can be configured by POSTing the necessary requests to the
-backend (possibly via a Web interface -- once we implement that).
+backend. To create a first instance, create a file ``instance.json``
+with an `InstanceConfigurationMessage`:
-FIXME: more details on how to setup instances here!
+::
+
+ {
+ payto_uris : [ "payto://iban/IBANNUMBERHERE" ],
+ id : "default",
+ name: "example.com",
+ address: { country : "zz" },
+ jurisdiction: { country : "zz" },
+ default_max_wire_fee: "KUDOS:1",
+ default_wire_fee_amortization: 100,
+ default_max_deposit_fee: "KUDOS:1",
+ default_wire_transfer_delay: { d_ms : 1209600000 },
+ default_pay_delay: { d_ms : 1209600000 },
+ }
+
+You can then create the instance using:
+::
+ $ wget --post-file=instance.json http://localhost:8888/private/instances
+The base URL for the instance will then be
+``http://localhost:8888/instances/default``. You can create additional
+instances by changing the "id" value to identifies other than "default".
+
+Endpoints to modify (reconfigure), permanently disable (while keeping the data)
+or purge (deleting all associated data) instances exist as well and are documented
+in the `Merchant Backend API documentation <#merchant-api>`__.
Accounts
@@ -689,10 +714,50 @@ 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://``-URL.
+The bank account information is provided in the form of a ``payto://``-URL.
+
+See RFC XXXX for the format of ``payto://``-URLs.
+
+
+.. _Inventory:
+
+Inventory management
+====================
+
+
+
+
+
+.. _Secure-setup:
+
+Secure setup
+============
+
+.. index:: security
+.. index:: TLS
+
+For additional security, you may want to have the backend bind to a UNIX
+domain socket and use an HTTP reverse proxy for TLS termination:
+
+ ::
+
+ $ taler-config -s MERCHANT -o SERVE -V UNIX
+ $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+
+Assuming your domain name is /example.com/ and you have TLS configured,
+a possible reverse proxy directive for Nginx would be:
+
+ ::
+
+ proxy_pass http://unix:/some/path/here.sock;
+ proxy_redirect off;
+ proxy_set_header Host $host;
+ proxy_set_header X-Forwarded-Host "example.com";
+ proxy_set_header X-Forwarded-Proto "https";
-FIXME: more details on how to setup accounts here!
+Leave out the last line if your Nginx reverse proxy does not have HTTPS
+enabled. Make sure to restart the /taler-merchant-httpd/ process after
+changing the configuration.
Upgrade procedure
@@ -726,40 +791,116 @@ your systemd or init system, or directly using:
$ taler-merchant-httpd
+.. _Tipping-visitors:
-Advanced topics
-===============
+Tipping visitors
+================
-.. _Secure-setup:
+.. index:: tipping
-Secure setup
-------------
+NOTE: This section is dated and should be reviewed!
-.. index:: security
-.. index:: TLS
+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.
-For additional security, you may want to have the backend bind to a UNIX
-domain socket and use an HTTP reverse proxy for TLS termination:
+There are four basic steps that must happen to tip a visitor.
- ::
+FIXME: write current explanation!
- $ taler-config -s MERCHANT -o SERVE -V UNIX
- $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+.. _Fund-the-reserve:
-Assuming your domain name is /example.com/ and you have TLS configured,
-a possible reverse proxy directive for Nginx would be:
+Fund the reserve
+----------------
- ::
+.. index:: reserve
+.. index:: close
- proxy_pass http://unix:/some/path/here.sock;
- proxy_redirect off;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Host "example.com";
- proxy_set_header X-Forwarded-Proto "https";
+In our example, the output for the wire transfer subject is:
-Leave out the last line if your Nginx reverse proxy does not have HTTPS
-enabled. Make sure to restart the /taler-merchant-httpd/ process after
-changing the configuration.
+::
+
+ QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
+
+You now need to make a wire transfer to the exchange’s bank account
+using the public key as the 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
+the “/private/reserves/$RID/tip-authorize” API of the backend. 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
+missconfigured 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/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
+===============
+
+.. _MerchantDatabaseScheme:
+
+Database Scheme
+---------------
+
+The merchant database must be initialized using taler-merchant-dbinit.
+This tool creates the tables required by the Taler merchant to operate.
+The tool also allows you to reset the Taler merchant database, which is
+useful for test cases but should never be used in production. Finally,
+taler-merchant-dbinit has a function to garbage collect a database,
+allowing administrators to purge records that are no longer required.
+
+The database scheme used by the merchant looks as follows:
+
+.. image:: merchant-db.png
@@ -890,92 +1031,7 @@ While the configuration file is typically located at
to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c``
option.
-.. _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 four basic steps that must happen to tip a visitor.
-
-FIXME: write current explanation!
-
-.. _Fund-the-reserve:
-
-Fund the reserve
-^^^^^^^^^^^^^^^^
-
-.. index:: reserve
-.. index:: close
-
-In our example, the output for the wire transfer subject is:
-
-::
-
- QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
-
-You now need to make a wire transfer to the exchange’s bank account
-using the public key as the 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
-the “/private/reserves/$RID/tip-authorize” API of the backend. 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
-missconfigured 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/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.
.. _Benchmarking:
@@ -984,6 +1040,8 @@ Benchmarking
.. index:: testing database
+NOTE: This section is dated and should be reviewed!
+
The merchant codebase offers the ``taler-merchant-benchmark`` tool to
populate the database with fake payments. This tool is in charge of
starting a merchant, exchange, and bank processes, and provide them all
@@ -1061,27 +1119,6 @@ topics that might be helpful to understand how the exchange operates,
which files should be backed up. The information may also be helpful for
diagnostics.
-.. _MerchantDatabaseScheme:
-
-Database Scheme
----------------
-
-The merchant database must be initialized using taler-merchant-dbinit.
-This tool creates the tables required by the Taler merchant to operate.
-The tool also allows you to reset the Taler merchant database, which is
-useful for test cases but should never be used in production. Finally,
-taler-merchant-dbinit has a function to garbage collect a database,
-allowing administrators to purge records that are no longer required.
-
-The database scheme used by the merchant looks as follows:
-
-.. image:: merchant-db.png
-
-
-
-Legacy
-======
-
This chapter contains some legacy documentation we need to update
before it can be considered even reasonably accurate.
@@ -1194,6 +1231,11 @@ purpose, issue the following command:
+
+
+Legacy
+======
+
Installing Taler using Docker
-----------------------------