specify current merchant configuration

1 files changed, 182 insertions, 126 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 8fcb487e..f8515c0a 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -312,6 +312,7 @@ instructions starting with the installation of libgnunetutil. Note that
 if you used the Debian wheezy instructions above, you need to pass
 ``--with-microhttpd=/usr/local/`` to all ``configure`` invocations.
 
+
 How to configure the merchant’s backend
 =======================================
 
@@ -386,7 +387,6 @@ Currency
 Which currency the Web shop deals in, i.e. “EUR” or “USD”, is
 specified using the option
 
-
    ::
 
       [TALER]/CURRENCY
@@ -449,45 +449,92 @@ To configure the Taler backend to use this database, run:
       $ taler-config -s MERCHANTDB-postgres -o CONFIG \
         -V postgres:///$DBNAME
 
+.. index: MASTER_KEY
+
 Exchange
 ^^^^^^^^
 
-To add an exchange to the list of trusted payment service providers,
-you create a section with a name that starts with “exchange-”. In
-that section, the following options need to be configured:
+To add an exchange to the list of trusted payment service providers, you
+create a section with a name that starts with “MERCHANT-EXCHANGE-”. In that
+section, the following options need to be configured:
 
-   -  The “url” option specifies the exchange’s base URL. For example,
-      to use the Taler demonstrator use:
+   -  The “EXCHANGE_BASE_URL” option specifies the exchange’s base URL. For example,
+      to use the Taler demonstrator, specify:
 
       ::
 
-         $ taler-config -s EXCHANGE-demo -o URL \
+         $ taler-config -s MERCHANT-EXCHANGE-demo \
+           -o EXCHANGE_BASE_URL \
            -V https://exchange.demo.taler.net/
 
-   -  master key
-      The “master_key” option specifies the exchange’s master public key
+   -  The “MASTER_KEY” option specifies the exchange’s master public key
       in base32 encoding. For the Taler demonstrator, use:
 
       ::
 
-         $ taler-config -s EXCHANGE-demo -o master_key \
+         $ taler-config -s MERCHANT-EXCHANGE-demo \
+           -o MASTER_KEY \
            -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
 
-Note that multiple exchanges can be added to the system by using
-different tokens in place of ``demo`` in the example above. Note
-that all of the exchanges must use the same currency. If you need
-to support multiple currencies, you need to configure a backend
-per currency.
+   -  The “CURRENCY” option specifies the exchange’s currency.
+      For the Taler demonstrator, use:
+
+      ::
+
+         $ taler-config -s MERCHANT-EXCHANGE-demo \
+           -o CURRENCY \
+           -V KUDOS
+
+Note that multiple exchanges can be added to the system by using different
+tokens in place of ``demo`` in the example above. Note that all of the
+exchanges must use the same currency: If the currency does not match the main
+currency from the "TALER" section, the exchange is ignored. If you need to
+support multiple currencies, you need to configure a backend per currency.
 
 
 
 Auditor
 ^^^^^^^
 
-FIXME: document here how to add an auditor to the list of
-trusted auditors!
+To add an auditor to the list of trusted auditors (which implies
+that all exchanges audited by this auditor will be trusted!)
+you create a section with a name that starts with “MERCHANT-AUDITOR-”. In
+that section, the following options need to be configured:
+
+   -  The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example,
+      to use the Taler demonstrator's auditor, specify:
+
+      ::
+
+         $ taler-config -s MERCHANT-AUDITOR-demo \
+           -o AUDITOR_BASE_URL \
+           -V https://exchange.demo.taler.net/
+
+   -  The “AUDITOR_KEY” option specifies the auditor's public key
+      in base32 encoding. For the Taler demonstrator, use:
+
+      ::
+
+         $ taler-config -s MERCHANT-AUDITOR-demo \
+           -o AUDITOR_KEY \
+           -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000
+
+   -  The “CURRENCY” option specifies the auditor’s currency.
+      For the Taler demonstrator, use:
+
+      ::
+
+         $ taler-config -s MERCHANT-AUDITOR-demo \
+           -o CURRENCY \
+           -V KUDOS
 
 
+Note that multiple auditors can be added to the system by using different
+tokens in place of ``demo`` in the example above. Note that all of the
+auditors must use the same currency: If the currency does not match the main
+currency from the "TALER" section, the auditor is ignored.  If you need to
+support multiple currencies, you need to configure a backend per currency.
+
 
 .. _Sample-backend-configuration:
 
@@ -511,13 +558,19 @@ The following is an example for a complete backend configuration:
    [MERCHANTDB-postgres]
    CONFIG = postgres:///donations
 
-   [merchant-exchange-trusted]
-   # FIXME: check this is up-to-date!
+   [merchant-exchange-NAME]
    EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
    MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+   # If currency does not match [TALER] section, the exchange
+   # will be ignored!
    CURRENCY = KUDOS
 
-   [FIXME: add example for AUDITOR!]
+   [merchant-auditor-NAME]
+   AUDITOR_BASE_URL = https://auditor.demo.taler.net/
+   AUDITOR_KEY = DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11
+   # If currency does not match [TALER] section, the auditor
+   # will be ignored!
+   CURRENCY = KUDOS
 
 Given the above configuration, the backend will use a database named
 ``donations`` within Postgres.
@@ -594,112 +647,6 @@ a ``payto://``-URL.
 FIXME: more details on how to setup accounts here!
 
 
-.. _Testing:
-
-Testing
-=======
-
-The tool ``taler-merchant-generate-payments`` can be used to test the
-merchant backend installation. It implements all the payment’s steps in
-a programmatically way, relying on the backend you give it as input.
-Note that this tool gets installed along all the merchant backend’s
-binaries.
-
-This tool gets configured by a config file, that must have the following
-layout:
-
-::
-
-   [PAYMENTS-GENERATOR]
-
-   # The exchange used during the test: make sure the merchant backend
-   # being tested accpets this exchange.
-   # If the sysadmin wants, she can also install a local exchange
-   # and test against it.
-   EXCHANGE = https://exchange.demo.taler.net/
-
-   # This value must indicate some URL where the backend
-   # to be tested is listening; it doesn't have to be the
-   # "official" one, though.
-   MERCHANT = http://localbackend/
-
-   # This value is used when the tool tries to withdraw coins,
-   # and must match the bank used by the exchange. If the test is
-   # done against the exchange at https://exchange.demo.taler.net/,
-   # then this value can be "https://bank.demo.taler.net/".
-   BANK = https://bank.demo.taler.net/
-
-   # The merchant instance in charge of serving the payment.
-   # Make sure this instance has a bank account at the same bank
-   # indicated by the 'bank' option above.
-   INSTANCE = default
-
-   # The currency used during the test. Must match the one used
-   # by merchant backend and exchange.
-   CURRENCY = KUDOS
-
-Run the test in the following way:
-
-::
-
-   $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL]
-
-The argument ``config`` given to ``-c`` points to the configuration file
-and is optional – ``^/.config/taler.conf`` will be checked by default.
-By default, the tool forks two processes: one for the merchant backend,
-and one for the exchange. The option ``-e`` (``-m``) avoids any exchange
-(merchant backend) fork, and just runs the generator against the
-exchange (merchant backend) running at ``EURL`` (``MURL``).
-
-Please NOTE that the generator contains *hardcoded* values, as for
-deposit fees of the coins it uses. In order to work against the used
-exchange, those values MUST match the ones used by the exchange.
-
-The following example shows how the generator "sets" a deposit fee of
-EUR:0.01 for the 5 EURO coin.
-
-::
-
-   // from <merchant_repository>/src/sample/generate_payments.c
-   { .oc = OC_PAY,
-     .label = "deposit-simple",
-     .expected_response_code = MHD_HTTP_OK,
-     .details.pay.contract_ref = "create-proposal-1",
-     .details.pay.coin_ref = "withdraw-coin-1",
-     .details.pay.amount_with_fee = concat_amount (currency, "5"),
-     .details.pay.amount_without_fee = concat_amount (currency, "4.99") },
-
-The logic calculates the deposit fee according to the subtraction:
-``amount_with_fee - amount_without_fee``.
-
-The following example shows a 5 EURO coin configuration - needed by the
-used exchange - which is compatible with the hardcoded example above.
-
-::
-
-   [COIN_eur_5]
-   value = EUR:5
-   duration_overlap = 5 minutes
-   duration_withdraw = 7 days
-   duration_spend = 2 years
-   duration_legal = 3 years
-   fee_withdraw = EUR:0.00
-   fee_deposit = EUR:0.01 # important bit
-   fee_refresh = EUR:0.00
-   fee_refund = EUR:0.00
-   rsa_keysize = 1024
-
-If the command terminates with no errors, then the merchant backend is
-correctly installed.
-
-After this operation is done, the merchant database will have some dummy
-data in it, so it may be convenient to clean all the tables; to this
-purpose, issue the following command:
-
-::
-
-   $ taler-merchant-dbinit -r
-
 
 Advanced topics
 ===============
@@ -1026,6 +973,115 @@ Legacy
 This chapter contains some legacy documentation we need to update
 before it can be considered even reasonably accurate.
 
+
+Taler payments generator
+------------------------
+
+This tool does not exist anymore right now...
+
+The tool ``taler-merchant-generate-payments`` can be used to test the
+merchant backend installation. It implements all the payment’s steps in
+a programmatically way, relying on the backend you give it as input.
+Note that this tool gets installed along all the merchant backend’s
+binaries.
+
+This tool gets configured by a config file, that must have the following
+layout:
+
+::
+
+   [PAYMENTS-GENERATOR]
+
+   # The exchange used during the test: make sure the merchant backend
+   # being tested accpets this exchange.
+   # If the sysadmin wants, she can also install a local exchange
+   # and test against it.
+   EXCHANGE = https://exchange.demo.taler.net/
+
+   # This value must indicate some URL where the backend
+   # to be tested is listening; it doesn't have to be the
+   # "official" one, though.
+   MERCHANT = http://localbackend/
+
+   # This value is used when the tool tries to withdraw coins,
+   # and must match the bank used by the exchange. If the test is
+   # done against the exchange at https://exchange.demo.taler.net/,
+   # then this value can be "https://bank.demo.taler.net/".
+   BANK = https://bank.demo.taler.net/
+
+   # The merchant instance in charge of serving the payment.
+   # Make sure this instance has a bank account at the same bank
+   # indicated by the 'bank' option above.
+   INSTANCE = default
+
+   # The currency used during the test. Must match the one used
+   # by merchant backend and exchange.
+   CURRENCY = KUDOS
+
+Run the test in the following way:
+
+::
+
+   $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL]
+
+The argument ``config`` given to ``-c`` points to the configuration file
+and is optional – ``^/.config/taler.conf`` will be checked by default.
+By default, the tool forks two processes: one for the merchant backend,
+and one for the exchange. The option ``-e`` (``-m``) avoids any exchange
+(merchant backend) fork, and just runs the generator against the
+exchange (merchant backend) running at ``EURL`` (``MURL``).
+
+Please NOTE that the generator contains *hardcoded* values, as for
+deposit fees of the coins it uses. In order to work against the used
+exchange, those values MUST match the ones used by the exchange.
+
+The following example shows how the generator "sets" a deposit fee of
+EUR:0.01 for the 5 EURO coin.
+
+::
+
+   // from <merchant_repository>/src/sample/generate_payments.c
+   { .oc = OC_PAY,
+     .label = "deposit-simple",
+     .expected_response_code = MHD_HTTP_OK,
+     .details.pay.contract_ref = "create-proposal-1",
+     .details.pay.coin_ref = "withdraw-coin-1",
+     .details.pay.amount_with_fee = concat_amount (currency, "5"),
+     .details.pay.amount_without_fee = concat_amount (currency, "4.99") },
+
+The logic calculates the deposit fee according to the subtraction:
+``amount_with_fee - amount_without_fee``.
+
+The following example shows a 5 EURO coin configuration - needed by the
+used exchange - which is compatible with the hardcoded example above.
+
+::
+
+   [COIN_eur_5]
+   value = EUR:5
+   duration_overlap = 5 minutes
+   duration_withdraw = 7 days
+   duration_spend = 2 years
+   duration_legal = 3 years
+   fee_withdraw = EUR:0.00
+   fee_deposit = EUR:0.01 # important bit
+   fee_refresh = EUR:0.00
+   fee_refund = EUR:0.00
+   rsa_keysize = 1024
+
+If the command terminates with no errors, then the merchant backend is
+correctly installed.
+
+After this operation is done, the merchant database will have some dummy
+data in it, so it may be convenient to clean all the tables; to this
+purpose, issue the following command:
+
+::
+
+   $ taler-merchant-dbinit -r
+
+
+
 Installing Taler using Docker
 -----------------------------