describe accounts and transfers (#8017)

1 files changed, 65 insertions, 18 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 78d10454..4d3ae4ee 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -587,7 +587,7 @@ section, the following options need to be configured:
 
    .. code-block:: ini
 
-      [MERCHANT-EXCHANGE-KUDOS]
+      [merchant-exchange-kudos]
       EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/"
 
 -  The ``MASTER_KEY`` option specifies the exchange’s master public key
@@ -595,7 +595,7 @@ section, the following options need to be configured:
 
    .. code-block:: ini
 
-      [MERCHANT-EXCHANGE-KUDOS]
+      [merchant-exchange-kudos]
       MASTER_KEY = "GNRJCH0HYKN59939JC0CJ2JDC7ZNEBSATJFF00CVS3WPG4TQEA7G"
 
   You can find out this key by running ``curl https://exchange.demo.taler.net/keys | jq .master_public_key``.
@@ -605,19 +605,19 @@ section, the following options need to be configured:
 
    .. code-block:: ini
 
-      [MERCHANT-EXCHANGE-KUDOS]
+      [merchant-exchange-kudos]
       CURRENCY = "KUDOS"
 
 
 Note that multiple exchanges can be added to the system by using different
 identifiers in place of ``KUDOS`` in the example above. Note that all of the
 exchanges actually used will use the same currency: If the currency does not
-match the main ``CURRENCY`` option from the ``TALER`` section, the respective
-``MERCHANT-EXCHANGE-`` section is automatically ignored. If you need support
+match the main ``CURRENCY`` option from the ``taler`` section, the respective
+``merchant-exchange-`` section is automatically ignored. If you need support
 for multiple currencies, you need to deploy one backend per currency.
 
 The merchant already ships with a default configuration that contains the
-``MERCHANT-EXCHANGE-KUDOS`` section from above.
+``merchant-exchange-kudos`` section from above.
 
 .. note::
 
@@ -639,21 +639,21 @@ The following is an example for a complete backend configuration:
 
 .. code-block:: ini
 
-   [TALER]
+   [taler]
    CURRENCY = KUDOS
 
-   [MERCHANT]
+   [merchant]
    SERVE = TCP
    PORT = 8888
    DATABASE = postgres
 
-   [MERCHANTDB-postgres]
+   [merchantdb-postgres]
    CONFIG = postgres:///donations
 
-   [merchant-exchange-NAME]
+   [merchant-exchange-kudos]
    EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
    MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
-   # If currency does not match [TALER] section, the exchange
+   # If currency does not match [taler] section, the exchange
    # will be ignored!
    CURRENCY = KUDOS
 
@@ -773,7 +773,6 @@ interface create a file ``instance.json`` with an
 .. code-block:: json
 
    {
-     "accounts" : [{"payto_uri":"$PAYTO_URI"}],
      "id" : "default",
      "name": "example.com",
      "address": { "country" : "zz" },
@@ -784,12 +783,7 @@ interface create a file ``instance.json`` with an
      "default_pay_delay": { "d_ms" : 1209600000 }
    }
 
-In the text above, you must replace ``$PAYTO_URI`` with your actual
-``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
+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
@@ -812,6 +806,59 @@ or purge (deleting all associated data) instances exist as well and are document
 in the :ref:`Merchant Backend API documentation <merchant-api>`.
 
 
+Accounts
+--------
+
+Before you can use an instance productively, you need to configure one or more
+bank accounts. These bank accounts will be provided to the Taler exchange
+operator to tell it where to wire the income from your sales. Every bank
+account has an associated *wire method* which determines how an exchange can
+transfer the funds.  The most commonly supported wire method is *iban*, which
+implies that bank accounts are identified by IBAN numbers and wire transfers
+are to be executed between IBAN accounts.
+
+Not every exchange will support every *wire method*, and if you do not add a
+bank account with a wire method that is supported by a particular exchange,
+then you will not be able to receive payments via that exchange even if you
+configured the merchant backend to trust that exchange.
+
+The simplest way to configure an account is to use the Web interface which
+has specific forms for different wire methods. Specifying the revenue gateway
+with username and password is optional and discussed below.
+
+Detecting Settlement: Manually Adding Transfers
+-----------------------------------------------
+
+The exchange may aggregate many small amounts into one larger wire transfer.
+If you want to safely determine for which orders have been settled (final
+payment from the exchange has been received), the backend must learn about the
+wire transfers made into your bank account. Basically, as a secure system, we
+do not simply trust a claim by the exchange that it would transfer the money,
+but we allow each merchant to check settlements.
+
+An easy (but somewhat tedious) way to check settlements is to manually add
+every wire transfer that a merchant bank account has received from the
+exchange with the total amount and the wire transfer subject. Given this
+information, the merchant backend will inquire with the exchange which
+individual payments were aggregated, check that the total amount is correct,
+and will then flag the respective contracts as wired.
+
+Automatic Settlement Data Import
+--------------------------------
+
+To automatically import settlement data, you can provide the merchant backend
+with the address and access credentials of a Taler revenue API for each bank
+account of an instance.  The revenue API endpoint will allow the merchant
+backend to observe all incoming wire transfers into your bank account and
+automatically import them into the list of wire transfers.
+
+Note that setting up a revenue API endpoint will usually require you to first
+ask your bank for EBICS access and to setup libeufin to provide the revenue
+API endpoint. The taler-bank used by regional currency setups also provides
+a revenue API endpoint.
+
+
+
 .. _Secure-setup:
 
 Secure setup