diff options
Diffstat (limited to 'texinfo/taler-merchant.texi')
| -rw-r--r-- | texinfo/taler-merchant.texi | 175 |
1 files changed, 89 insertions, 86 deletions
diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi index af3159e5..738d7804 100644 --- a/texinfo/taler-merchant.texi +++ b/texinfo/taler-merchant.texi @@ -21,11 +21,11 @@ @copying @quotation -GNU Taler 0.8.0pre0, Jan 27, 2021 +GNU Taler 0.8.0pre0, Apr 26, 2021 GNU Taler team -Copyright @copyright{} 2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -242,7 +242,7 @@ special currency “KUDOS” and includes its own special bank. @geindex frontend -@geindex back office +@geindex back-office @geindex backend @@ -257,7 +257,7 @@ components: @itemize - @item -A frontend which interacts with the customer’s browser. The frontend +A @emph{frontend} which interacts with the customer’s browser. The frontend enables the customer to build a shopping cart and place an order. Upon payment, it triggers the respective business logic to satisfy the order. This component is not included with Taler, but rather @@ -266,21 +266,21 @@ The Merchant API Tutorial gives an introduction for how to integrate Taler with Web shop frontends. @item -A back office application that enables the shop operators to view +A @emph{back-office} application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied. This component is not included with Taler, but rather assumed to exist at the merchant. The Merchant Backend API provides the API specification that should be reviewed to integrate such a -back office with the Taler backend. +back-office with the Taler backend. @item -A Taler-specific payment backend which makes it easy for the frontend +A Taler-specific payment @emph{backend} which makes it easy for the frontend to process financial transactions with Taler. This manual primarily describes how to install and configure this backend. @item -A DBMS which stores the transaction history for the Taler backend. +A @emph{DBMS} which stores the transaction history for the Taler backend. For now, the GNU Taler reference implementation only supports Postgres, but the code could be easily extended to support another DBMS. Please review the Postgres documentation for details on @@ -299,7 +299,7 @@ Taler-specific financial information in a DBMS and communicates with the GNU Taler exchange over the Internet. The frontend accesses the backend via a RESTful API. As a result, the frontend never has to directly communicate with the exchange, and also does not deal with sensitive data. In particular, the -merchant’s signing keys and bank account information is encapsulated within +merchant’s signing keys and bank account information are encapsulated within the Taler backend. A typical deployment will additionally include a full-blown Web server (like @@ -348,7 +348,7 @@ the main Taler configuration (accepted currency, exchanges and auditors). To receive payments, an instance must have configured one or more bank @emph{accounts}. The backend does not have accounts for users, and instances are -also not really ‘accounts’. So whenever we use the term @emph{account}, it is about +also not really 'accounts'. So whenever we use the term @emph{account}, it is about a bank account of a merchant. @node Inventory,Orders and Contracts,Accounts,Terminology @@ -406,7 +406,7 @@ merchant, where the merchant specifies the specific terms of the order. After an order is created, it is @emph{claimed} by a wallet. Once an order is claimed by a specific wallet, only that wallet will be able to pay for this order, to the exclusion of other wallets even if they see the same order URL. -Sharing order URLs is explicitly allowed: if a user shares and order URL +Sharing order URLs is explicitly allowed: if a user shares an order URL with another user, that other user should be given the opportunity to purchase the same product. @@ -447,7 +447,7 @@ decade), contract information is deleted. The Taler backend can be used to verify that the exchange correctly wired all of the funds to the merchant. However, the backend does not have access to the -incoming wire transfers of the merchant’s bank account. Thus, merchants must +incoming wire transfers of the merchant's bank account. Thus, merchants must manually provide the backend with wire @emph{transfer} data that specifies the wire transfer subject and the amount that was received. Given this information, the backend can detect and report any irregularities that might arise. @@ -621,7 +621,7 @@ shared object libraries (@code{.so} files) visible to the various installed programs. There is no need to actually run a GNUnet peer to use the Taler merchant -backend – all the merchant needs from GNUnet is a number of headers and +backend -- all the merchant needs from GNUnet is a number of headers and libraries! @node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source @@ -649,7 +649,7 @@ which requires you to run the last step as @code{root}. You have to specify previous step. There is no need to actually run a Taler exchange to use the Taler merchant -backend – all the merchant needs from the Taler exchange is a few headers and +backend -- all the merchant needs from the Taler exchange is a few headers and libraries! @node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source @@ -1155,7 +1155,7 @@ $ taler-config -s TALER -o CURRENCY -V KUDOS @subsection Database -In principle is possible for the backend to support different DBMSs. +In principle it is possible for the backend to support different DBMSs. The option @example @@ -1163,7 +1163,7 @@ The option @end example specifies which DBMS is to be used. However, currently only the value -“postgres” is supported. This is also the default. +@code{postgres} is supported. This is also the default. In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database. @@ -1178,7 +1178,7 @@ This option specifies a postgres access path using the format @code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the Postgres database you want to use. Suppose @code{$USER} is the name of the user who will run the backend process. Then, you need to first -run +run: @example $ sudo -u postgres createuser -d $USER @@ -1216,6 +1216,7 @@ the Postgres documentation. Commands, like @code{taler-merchant-dbinit}, that support the @code{-l LOGFILE} command-line option, send logging output to standard error by default. +See manpages/taler-merchant-dbinit.1 for more information. @c index: MASTER_KEY @@ -1232,8 +1233,8 @@ section, the following options need to be configured: @itemize - @item -The “EXCHANGE_BASE_URL” option specifies the exchange’s base URL. For example, -to use the Taler demonstrator, specify: +The @code{EXCHANGE_BASE_URL} option specifies the exchange’s base URL. +For example, to use the Taler demonstrator, specify: @example $ taler-config -s MERCHANT-EXCHANGE-demo \ @@ -1242,17 +1243,17 @@ $ taler-config -s MERCHANT-EXCHANGE-demo \ @end example @item -The “MASTER_KEY” option specifies the exchange’s master public key +The @code{MASTER_KEY} option specifies the exchange’s master public key in base32 encoding. For the Taler demonstrator, use: @example $ taler-config -s MERCHANT-EXCHANGE-demo \ -o MASTER_KEY \ - -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 + -V FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0 @end example @item -The “CURRENCY” option specifies the exchange’s currency. +The @code{CURRENCY} option specifies the exchange’s currency. For the Taler demonstrator, use: @example @@ -1263,9 +1264,9 @@ $ taler-config -s MERCHANT-EXCHANGE-demo \ @end itemize Note that multiple exchanges can be added to the system by using different -tokens in place of @code{demo} in the example above. Note that all of the +tokens in place of @code{demo} in the examples 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 +currency from the @code{TALER} section, the exchange is ignored. If you need to support multiple currencies, you need to configure a backend per currency. @node Auditor,,Exchange,Backend options @@ -1282,8 +1283,8 @@ that section, the following options need to be configured: @itemize - @item -The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example, -to use the Taler demonstrator’s auditor, specify: +The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL. +For example, to use the Taler demonstrator's auditor, specify: @example $ taler-config -s MERCHANT-AUDITOR-demo \ @@ -1292,17 +1293,17 @@ $ taler-config -s MERCHANT-AUDITOR-demo \ @end example @item -The “AUDITOR_KEY” option specifies the auditor’s public key +The @code{AUDITOR_KEY} option specifies the auditor's public key in base32 encoding. For the Taler demonstrator, use: @example $ taler-config -s MERCHANT-AUDITOR-demo \ -o AUDITOR_KEY \ - -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 + -V DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11 @end example @item -The “CURRENCY” option specifies the auditor’s currency. +The @code{CURRENCY} option specifies the auditor’s currency. For the Taler demonstrator, use: @example @@ -1313,9 +1314,9 @@ $ taler-config -s MERCHANT-AUDITOR-demo \ @end itemize Note that multiple auditors can be added to the system by using different -tokens in place of @code{demo} in the example above. Note that all of the +tokens in place of @code{demo} in the examples 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 +currency from the @code{TALER} section, the auditor is ignored. If you need to support multiple currencies, you need to configure a backend per currency. @node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend @@ -1359,7 +1360,7 @@ Given the above configuration, the backend will use a database named The backend will deposit the coins it receives to the exchange at @indicateurl{https://exchange.demo.taler.net/}, which has the master key -“FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0”. +@code{FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0}. Please note that @code{doc/config.sh} will walk you through all configuration steps, showing how to invoke @code{taler-config} for each of @@ -1409,7 +1410,7 @@ and use TLS for improved network privacy, see @ref{9,,Secure setup}. @chapter Instance setup -Before using the backend, you must at least configure the “default” instance. +Before using the backend, you must at least configure the "default" instance. @menu * KUDOS Accounts:: @@ -1430,12 +1431,13 @@ 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 @code{payto://}-URI. -See RFC 8905 for the format of @code{payto://}-URIs. +See RFC 8905@footnote{https://tools.ietf.org/html/rfc8905} +for the format of @code{payto://}-URIs. For first tests, you should sign up for a KUDOS bank account at @indicateurl{https://bank.demo.taler.net/}. -In this case, the payto://-URI will be of the form -“payto://x-taler-bank/bank.demo.taler.net/$USERNAME” where “$USERNAME” +In this case, the @code{payto://}-URI will be of the form +@code{payto://x-taler-bank/bank.demo.taler.net/$USERNAME} where @code{$USERNAME} must be replaced with the name of the account that was established at @indicateurl{https://bank.demo.taler.net/}. @@ -1446,17 +1448,17 @@ at @indicateurl{https://bank.demo.taler.net/}. 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 real bank +(such as EUR, USD, CHF) and provide a @code{payto://}-URI of your real 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” where -“$IBAN” must be replaced with the actual IBAN number. +IBAN, the corresponding @code{payto://}-URI is simply @code{payto://iban/$IBAN} where +@code{$IBAN} must be replaced with the actual IBAN number. @node Setup,,IBAN Accounts,Instance setup @anchor{taler-merchant-manual setup}@anchor{33} @section Setup -With the knowledge of the payto://-URI, instances can be configured by POSTing +With the knowledge of the @code{payto://}-URI, instances can be configured by POSTing a request to @code{POST /private/instances}. To create a first instance, create a file @code{instance.json} with an InstanceConfigurationMessage @@ -1466,6 +1468,7 @@ create a file @code{instance.json} with an InstanceConfigurationMessage "id" : "default", "name": "example.com", "address": @{ "country" : "zz" @}, + "auth": @{ "method" : "external"@} , "jurisdiction": @{ "country" : "zz" @}, "default_max_wire_fee": "KUDOS:1", "default_wire_fee_amortization": 100, @@ -1475,10 +1478,10 @@ create a file @code{instance.json} with an InstanceConfigurationMessage @} @end example -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 +In the text above, you must replace @code{$PAYTO_URI} with your actual +@code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the +setup is for an actual bank. The @code{name} field will be shown as the name of +your shop. The @code{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 @@ -1493,7 +1496,7 @@ $ wget --post-file=instance.json http://localhost:8888/private/instances The base URL for the instance will then be @code{http://localhost:8888/instances/default}. You can create additional -instances by changing the “id” value to identifies other than “default”. +instances by changing the @code{id} value to identifies other than @code{default}. Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented @@ -1534,9 +1537,9 @@ $ taler-config -s MERCHANT -o SERVE -V UNIX $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock @end example -Do not use a UNIX domain socket path in “/tmp”: systemd (or other init -systems) may give Web servers a private “/tmp” thereby hiding UNIX domain -sockets created by other users/processes in “/tmp”. +Do not use a UNIX domain socket path in "/tmp": systemd (or other init +systems) may give Web servers a private "/tmp" thereby hiding UNIX domain +sockets created by other users/processes in "/tmp". If UNIX domain sockets are for some reason not possible, you @emph{may} use a host-based firewall to block access to the TCP port of the merchant backend, @@ -1579,8 +1582,8 @@ process after changing the @code{SERVE} configuration. @subsection Apache -In Apache, make sure you have “mod_proxy”, “mod_proxy_http” and -“mod_headers” enabled: +In Apache, make sure you have @code{mod_proxy}, @code{mod_proxy_http} and +@code{mod_headers} enabled: @example $ a2enmod proxy @@ -1599,7 +1602,7 @@ RequestHeader add "X-Forwarded-Proto" "https" @end example Note that the above again assumes your domain name is @code{example.com} and that -you have TLS configured. Note that you must add the “https” header unless +you have TLS configured. Note that you must add the @code{https} header unless your site is not available via TLS. The above configuration(s) are both incomplete. You must still additionally @@ -1647,10 +1650,10 @@ location ~ /private/ @{ @} @end example -Here, “SECURITYTOKEN” should be replaced with the actual shared secret. Note -that the “~” ensures that the above matches all endpoints that include the -string “/private/”. If you only run a single instance, you could simply -specify “/private/” without the “~” to only configure the access policy for +Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret. Note +that the @code{~} ensures that the above matches all endpoints that include the +string @code{/private/}. If you only run a single instance, you could simply +specify @code{/private/} without the @code{~} to only configure the access policy for the default instance. If you are running different instances on the same backend, you @@ -1662,22 +1665,22 @@ location ~ ^/instances/foo/private/ @{ if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") @{ return 401; @} - proxy_pass ...; // as above + proxy_pass ...; # as above @} location ~ ^/instances/bar/private/ @{ if ($http_authorization !~ "(?i)ApiKey BARTOKEN") @{ return 401; @} - proxy_pass ...; // as above + proxy_pass ...; # as above @} location /private/ @{ if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") @{ return 401; @} - proxy_pass ...; // as above + proxy_pass ...; # as above @} location ~ /private/ @{ - return 401; // access to instances not explicitly configured is forbidden + return 401; # access to instances not explicitly configured is forbidden @} @end example @@ -1686,7 +1689,7 @@ location ~ /private/ @{ @subsection Apache -For Apache, you should first enable “mod_rewrite”: +For Apache, you should first enable @code{mod_rewrite}: @example $ a2enmod rewrite @@ -1704,10 +1707,10 @@ ProxyPass "unix:/some/path/here.sock|http://example.com/" </Location> @end example -Here, “SECURITYTOKEN” should be replaced with the actual shared secret. Note -that the “(.+)” ensures that the above matches all endpoints that include the -string “/private/”. If you only run a single instance, you could simply -specify “/private/” without the “~” to only configure the access policy for +Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret. Note +that the @code{(.+)} ensures that the above matches all endpoints that include the +string @code{/private/}. If you only run a single instance, you could simply +specify @code{/private/} without the @code{~} to only configure the access policy for the default instance. If you are running different instances on the same backend, you @@ -1807,10 +1810,10 @@ preferences indicated by the browser is returned. All of the static files must fit into memory and it must be possible for the process to hold open file handles for all of these files. You may want -to increase the “ulimit” of the @code{taler-merchant-httpd} process if you have +to increase the @code{ulimit} of the @code{taler-merchant-httpd} process if you have templates for many languages. -The backend determines the MIME type based on the file’s extension. The list +The backend determines the MIME type based on the file's extension. The list of supported extensions is hard-coded and includes common text and image formats. @@ -1881,7 +1884,7 @@ There are three basic steps that must happen to tip a visitor. 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: +10 KUDOS at instance @code{default} using the demo exchange, use: @example $ taler-merchant-setup-reserve \ @@ -1891,11 +1894,11 @@ $ taler-merchant-setup-reserve \ @end example The above command assumes that the merchant runs on localhost on -port 8888. The current implementation of the tool does not yet support -transmission of authentication information to the backend -(see bug 6418@footnote{https://bugs.gnunet.org/view.php?id=6418}). +port 8888. +For more information, including how to transmit authentication information +to the backend, see manpages/taler-merchant-setup-reserve.1. -The command will output a payto:// URI which specifies where to +The command will output a @code{payto://} URI which specifies where to wire the funds and which wire transfer subject to use. FIXME: add full example output. @@ -1910,7 +1913,7 @@ 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 -“@indicateurl{https://exchange/reserves/QPE24X}…” whether your transfer has arrived at the +“@indicateurl{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 @@ -2092,7 +2095,7 @@ The tool @code{taler-config} can be used to extract or manipulate configuration values; however, the configuration use the well-known INI file format and can also be edited by hand. -Run +Run: @example $ taler-config -s $SECTION @@ -2100,7 +2103,7 @@ $ taler-config -s $SECTION to list all of the configuration values in section @code{$SECTION}. -Run +Run: @example $ taler-config -s $section -o $option @@ -2109,7 +2112,7 @@ $ taler-config -s $section -o $option to extract the respective configuration value for option @code{$option} in section @code{$section}. -Finally, to change a setting, run +Finally, to change a setting, run: @example $ taler-config -s $section -o $option -V $value @@ -2158,7 +2161,7 @@ need, or will not need initially. The merchant codebase offers the @code{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 +starting a merchant, exchange, and bank processes, and provides them all the input to accomplish payments. Note that each component will use its own configuration (as they would do in production). @@ -2181,13 +2184,13 @@ start. The @code{taler-merchant-benchmark} tool will automatically launch and configure the exchange, (Python) bank and other tools required for the benchmark. However, the configuration file must be provided and have consistent options set. The -options that require special care include the exchange’s public key (which +options that require special care include the exchange's public key (which must match the private key in the file specified by the configuration), the currency (which must be consistent across the file), the denomination structure (which must enable payments in the range of 100ths of the unit currency (often called cents)). Furthermore, the benchmark will set the -Exchange bank account password to be “x”, so the configuration must also -specify “x” for the passphrase. Finally, the bank must be configured to allow +Exchange bank account password to be "x", so the configuration must also +specify "x" for the passphrase. Finally, the bank must be configured to allow for substantial debt least the transactions by the benchmark run out of digital cash. @@ -2319,11 +2322,11 @@ rsa_keysize = 1024 @end example -Note that the public key must match the exchange’s +Note that the public key must match the exchange's private key and that the Postgres database must exist before launching the benchmark. You also -will need to ensure that the Exchange’s -details are setup. +will need to ensure that the Exchange's +details are set up. For details, see the Exchange Operator Manual. @node Running the benchmark command,,Benchmark setup,Advanced experimental features @@ -2342,7 +2345,7 @@ one of them being mandatory: section specifies the bank account for the exchange that should be used for the benchmark. For the example configuration above, the SECTION value provided must be -“exchange-account-exchange”. +@code{exchange-account-exchange}. @end itemize The tool comes with two operation modes: @emph{ordinary}, and @emph{corner}. @@ -2353,7 +2356,7 @@ use merchant instances other than the default (which is, actually, the one used by default by the tool). Note: the ability of driving the aggregation policy is useful for testing -the backoffice facility. +the back-office facility. Any subcommand is also equipped with the canonical @code{--help} option, so feel free to issue the following command in order to explore all the @@ -2391,7 +2394,7 @@ options: @item @code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking operations. Note that the @strong{total} amount of operations will be two -times @emph{TN}, since “one” tracking operation accounts for +times @emph{TN}, since "one" tracking operation accounts for @code{/track/transaction} and @code{/track/transfer}. This command should only be used to see if the operation ends without problems, as no actual measurement of performance is provided (despite of the @@ -2459,7 +2462,7 @@ this stage of development, you should also ignore some (harmless) error message from postresql about already existing roles and databases. To test if everything worked as expected, it suffices to issue a simple -request to the merchant, as: +request to the merchant, for example: @example $ curl http://$(docker-machine ip)/ |