diff options
Diffstat (limited to 'taler-merchant-manual.rst')
| -rw-r--r-- | taler-merchant-manual.rst | 428 |
1 files changed, 304 insertions, 124 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 4959dd48..48605a55 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -18,8 +18,13 @@ .. _taler-merchant-backend-operator-manual: -GNU Taler Merchant Backend Operator Manual -########################################## +Merchant Backend Operator Manual +################################ + +.. contents:: Table of Contents + :depth: 1 + :local: + Introduction ============ @@ -42,17 +47,6 @@ We expect some moderate familiarity with the compilation and installation of Free Software packages. An understanding of cryptography is not required. -This first chapter of the manual will give a brief overview of the -overall Taler architecture, describing the environment in which the -Taler backend operates. The second chapter then explains how to install -the software, including key dependencies. The third chapter will explain -how to configure the backend, including in particular the configuration -of the bank account details of the merchant. - -The last chapter gives some additional information about advanced topics -which will be useful for system administrators but are not necessary for -operating a basic backend. - .. _Architecture-overview: Architecture overview @@ -152,11 +146,12 @@ main Taler configuration (especially the accepted *currency* and *exchanges*). acceptable to consider instances to be the "users" or "accounts" of a merchant backend and the bearer token is equivalent to a passphrase. +.. _instance-bank-account: Instance Bank Accounts ---------------------- -.. index:: instance-bank-account +.. index:: Bank account To receive payments, an instance must have configured one or more bank *accounts*. When configuring the bank account of an instance, one should @@ -260,6 +255,61 @@ After the *legal expiration* (by default: a decade), contract information is deleted when running the garbage collector using ``taler-merchant-dbinit``. +.. _template: + +Templates +--------- + +.. index:: Template + +Usually, a merchant must use an authenticated endpoint to create an order and +then share the link to the order with a wallet. Templates are a mechanism that +allows wallets to create their own orders directly, using a public endpoint. +The template fixes some properties of the contracts created from it, while +other details may be left for the customer to provide. Templates are useful +in cases where the point-of-sale of a merchant is offline (and thus cannot +setup an order), or even in cases where a simple static QR code is desired to +accept payments or donations. + +When generating a template, the "summary" text of the contract and the +"amount" to be paid by the customer can be fixed or left for the customer to +specify. If the customer is expected to provide either or both of these +values, the template link (or QR code) can specify a default value. For +example, a cafeteria with a fixed price lunch may use a "lunch" template with +both values fixed to the lunch price and the "lunch" product, a bakery might +fix the summary to "baked goods" but allow the customer to enter the amount +based on the total price of the items being bought, and a charity may allow +donating an arbitrary amount and summary message while also suggesting default +values. + +If an offline merchant wants to confirm that a customer did actually pay the +agreed amount using an order derived from a template, they can associate an +OTP device with the template. + + +.. _otp-device: + +OTP Devices +----------- + +.. index:: OTP +.. index:: TOTP + +A One-Time-Password (OTP) generator is a device or application that generates +a 4 to 8 digit code typically used for authentication. The widely used TOTP +standard is described in `RFC 6238 <https://www.rfc-editor.org/rfc/rfc6238>`_. +For GNU Taler merchant backends, OTP devices are used as a way to assure a +merchant without network connectivity that a customer made a digital +payment. The idea is described in depth in our `SUERF Policy Brief +<https://www.suerf.org/suer-policy-brief/69851/practical-offline-payments-using-one-time-passcodes>`_. +To use this method, a merchant must configure the OTP device's shared secret +in the merchant backend, and then associate the OTP device with a +:ref:`template`. Once the customer has paid, they are given a list of OTP +codes which must be shown to the merchant who can check that at least one of +the codes matches their OTP device, proving that the customer made the +payment. + + Transfers --------- @@ -273,55 +323,51 @@ the backend does not have access to the incoming wire transfers of the merchant's bank account. In this case, merchants should manually provide the backend with wire *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. +detect and report any irregularities that might arise. -Rewards -------- -.. index:: reward -.. index:: pick up +Webhooks +-------- -Taler does not only allow a Website to be paid, but also to make voluntary, -non-contractual payments to visitors, called *rewards*. Such rewards could be -granted as a reward for filling in surveys or watching advertizements. For -rewards, there is no contract, rewards are always voluntary actions by the Web -site that do not arise from a contractual obligation. Before a Web site -can create rewards, it must establish a reserve. Once a reserve has been -established, the merchant can *grant* rewards, allowing wallets to *pick up* -the reward. +.. index:: webhook -.. note:: +A webhook is a pre-defined HTTP request that the GNU Taler merchant backend +will make upon certain events, such as an order being paid or refunded. When +the configured event happens, the merchant backend will make an HTTP request +to the endpoint configured in the webhook configuration, possibly sending +selected data about the event to the respective Web service. Webhooks can be +used to trigger additional business logic outside of the GNU Taler merchant +backend. - Rewards are an optional feature, and exchanges may disable rewards (usually - if they see compliance issues). In this case, the reward feature will - not be available. +Installation +============ -Reserves --------- +This chapter describes how to install the GNU Taler merchant backend. -.. index:: reserve -.. index:: close +.. _Generic-instructions: -A *reserve* is a pool of electronic cash at an exchange under the control of -a private key. Merchants withdraw coins from a reserve when granting -rewards. A reserve is established by first generating the required key material -in the merchant backend, and then wiring the desired amount of funds to the -exchange. +Installing the GNU Taler binary packages on Debian +-------------------------------------------------- -An exchange will automatically *close* a reserve after a fixed period of time -(typically about a month), wiring any remaining funds back to the merchant. -While exchange APIs exists to (1) explicitly *open* a reserve to prevent it -from being automatically closed and to (2) explicitly *close* a reserve at any -time, the current merchant backend does not make use of these APIs. +.. include:: frags/installing-debian.rst +.. include:: frags/apt-install-taler-merchant.rst -Installation -============ -This chapter describes how to install the GNU Taler merchant backend. +Installing the GNU Taler binary packages on Trisquel +---------------------------------------------------- + +.. include:: frags/installing-trisquel.rst + + +Installing the GNU Taler binary packages on Ubuntu +-------------------------------------------------- + +.. include:: frags/installing-ubuntu.rst + +.. include:: frags/apt-install-taler-merchant.rst -.. _Generic-instructions: Installing from source ---------------------- @@ -360,30 +406,9 @@ libraries! .. include:: frags/install-before-check.rst -Installing the GNU Taler binary packages on Debian --------------------------------------------------- - -.. include:: frags/installing-debian.rst - -.. include:: frags/apt-install-taler-merchant.rst - -Installing the GNU Taler binary packages on Trisquel ----------------------------------------------------- - -.. include:: frags/installing-trisquel.rst - - -Installing the GNU Taler binary packages on Ubuntu --------------------------------------------------- - -.. include:: frags/installing-ubuntu.rst - -.. include:: frags/apt-install-taler-merchant.rst - - -How to configure the merchant’s backend -======================================= +How to configure the merchant backend +===================================== .. index:: taler.conf @@ -536,7 +561,7 @@ For the ``postgres`` backend, you need to specify: [merchantdb-postgres] CONFIG = "postgres:///taler-merchant" -This option specifies a PostgreSQL access path, typicallly using the format +This option specifies a PostgreSQL access path, typically using the format ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the PostgreSQL database you want to use (here, ``taler-merchant`` on the local machine). Suppose ``$USER`` is the name of the user who will run the backend process @@ -648,7 +673,7 @@ The following is an example for a complete backend configuration: DATABASE = postgres [merchantdb-postgres] - CONFIG = postgres:///donations + CONFIG = postgres:///taler-merchant [merchant-exchange-kudos] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ @@ -674,20 +699,17 @@ Launching the backend .. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the -merchant backend as ``$USER`` using +merchant backend as ``$USER`` using (to provide a trivial example): .. code-block:: console $ taler-merchant-httpd & $ taler-merchant-webhook & $ taler-merchant-wirewatch & + $ taler-merchant-depositcheck & + $ taler-merchant-exchange & -You only need to run ``taler-merchant-webhook`` if one of the instances is -configured to trigger web hooks. Similarly, ``taler-merchant-wirewatch`` is -only required if instances have accounts configured with automatic import of -wire transfers via a bank wire gateway. - -To ensure these processes runs always in the background and also after +To ensure these processes run always in the background and also after rebooting, you should use systemd, cron or some other init system of your operating system to launch the process. You should also periodically re-start these services to prevent them from exhausing the memory utilization of the @@ -698,8 +720,8 @@ how to start and stop daemons. When using the Debian/Ubuntu packages, the systemd configuration will already exist. You only need to enable and start the service - using ``systemctl enable taler-merchant-httpd`` and - ``systemctl start taler-merchant-httpd``. Additionally, you should + using ``systemctl enable taler-merchant.target`` and + ``systemctl start taler-merchant.target``. Additionally, you should review the ``/etc/apache2/sites-available/taler-merchant.conf`` or ``/etc/nginx/sites-available/taler-merchant`` (these files contain additional instructions to follow), symlink it to @@ -707,7 +729,6 @@ how to start and stop daemons. should be able to visit the merchant backend at the respective HTTP(S) endpoint. - If everything worked as expected, the command .. code-block:: console @@ -719,7 +740,7 @@ should return some basic configuration status data about the service. Please note that your backend might then be globally reachable without any access control. You can either: - * Use the ``--auth=$TOKEN`` command-line option to set an access token to be provided in an ``Authorize: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. + * Use the ``--auth=$TOKEN`` command-line option to **taler-merchant-httpd** to set an access token to be provided in an ``Authorize: Bearer $TOKEN`` HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. * Set the ``TALER_MERCHANT_TOKEN`` environment variable to ``$TOKEN`` for the same effect. This method has the advantage of ``$TOKEN`` not being visible as a command-line interface to other local users on the same machine. * Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token! @@ -734,15 +755,14 @@ and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>` Instance setup ============== -First of all, we recommend the use of the single-page administration -application (SPA) that is served by default at the base URL of the merchant -backend. You can use it to perform all steps described in this section (and -more!), using a simple Web interface instead of the ``wget`` commands given -below. +We recommend the use of the single-page administration application (SPA) that +is served by default at the base URL of the merchant backend. You can use it +to perform all steps described in this section (and more!), using a simple Web +interface. Alternatively, you can also use the ``wget`` commands given below. -Regardless of which tool you use, the first step for using the backend +Regardless of which approach you use, the first step for using the backend involves the creation of a ``default`` instance. The ``default`` instance can -also create / delete / configure other instances, similar to the ``root`` +also create, configure or delete other instances, similar to the ``root`` account on UNIX. When no instance exists and ``taler-merchant-httpd`` was started without the ``--auth`` option, then the backend is reachable without any access control (unless you configured some in the reverse proxy). @@ -761,8 +781,33 @@ times, once for each instance. :ref:`reverse proxy <reverse-proxy-configuration>`. -Setup without the Web interface -------------------------------- +Instance setup with the SPA +--------------------------- + +In order to setup an instance, you need the merchant backend to already be +running, and you must either have the credentials for the "default" instance, +or no instance must be configured at all yet. + +To start, point your browser to ``$PROTO://backend.$DOMAIN_NAME/``, replacing +"$PROTO" with "https" or (rarely) "http" and "$DOMAIN_NAME" with your +organizations DNS domain or subdomain. + +.. note:: + + The label "backend" here is also just a suggestion, your administrator + can in principle choose any name. + +You should be welcomed by the following merchant backoffice page: + +.. image:: screenshots/merchant_first_login.png + +After supplying the required fields, primarily the name of your organization +and the desired access token, click ``confirm``. You can change the instance +settings later via the ``Settings`` entry in the menu on the left. + + +Instance setup without the Web interface +---------------------------------------- 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 @@ -774,7 +819,7 @@ interface create a file ``instance.json`` with an { "id" : "default", - "name": "example.com", + "name": "Example Inc.", "address": { "country" : "zz" }, "auth": { "method" : "external"} , "jurisdiction": { "country" : "zz" }, @@ -805,9 +850,10 @@ 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 :ref:`Merchant Backend API documentation <merchant-api>`. +.. _instance-account-setup: -Accounts --------- +Instance account setup +====================== 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 @@ -815,16 +861,47 @@ 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. +are to be executed between IBAN accounts. For regional currency setups, the +wire method could also be *x-taler-bank*. + +.. note:: + + When using a regional currency, you need to first create a bank account at + the regional bank. You may need to contact the respective administrator who + can set one up. After being able to login to the new bank account, you can + see your bank account number by clicking on the ``Welcome, $USERNAME`` + message in the profile page. Next to the bank account number, you can find + a convenient button to copy the number to the clipboard. 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. +The simplest way to configure an account is to use the Web interface which has +specific forms for different wire methods. First, select ``Bank account`` at +the left of the page. The following page should be shown: + +.. image:: screenshots/no_default_account_yet.png + +Click on the blue "+" sign on the top right of the page to add a new +bank account. The following page should appear: + +.. image:: screenshots/enter_instance_details.png + +First, you should select the wire method, after which the dialog will show you +additional fields specific to the wire method. For example, if youchoose +``iban`` as the account type, the following page should appear: + +.. image:: screenshots/instance_iban_config.png + +Specifying the revenue gateway with username and password is optional and +discussed in section :ref:`automatic-settlement-data-import` below. + +After providing the details and confirming, the shop is ready to generate orders +and accept payments. + + Detecting Settlement: Manually Adding Transfers ----------------------------------------------- @@ -843,21 +920,55 @@ 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. +You can manually enter wire transfers under ``Transfers``. However, this is +tedious, and so if your banking setup supports it, we highly recommend +using the automatic settlement data import. + +.. _automatic-settlement-data-import: + 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. +To automatically import settlement data, you need to provide the merchant +backend with the address and access credentials of a +:ref:`taler-bank-merchant-http-api` for each bank account of an instance. The +revenue API endpoint will allow the merchant backend to obtain a list of all +incoming wire transfers into your bank account and automatically import them +into the list of confirmed 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. +ask your bank for EBICS access and to set up :ref:`libeufin-nexus` to provide +the revenue API endpoint. The :ref:`libeufin-bank` used by regional currency +setups also provides a revenue API endpoint at +``$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/``. Thus, when using a +regional currency setup, simply use the ``$BANK_URL`` of your bank and specify +your bank login name and password in the :ref:`instance-account-setup` dialog. +Manually creating an order using the SPA +======================================== + +Click on ``Orders`` at the top left corner of the merchant backoffice page; the +following page should appear + +.. image:: screenshots/create_orders.png + +After having filled the required fields, the interface should show the +following page with the related links to check the status of the order and let +wallets pay for it. + +.. image:: screenshots/payment_links.png + +In order to test the setup, it should be now possible to use the command line wallet +to withdraw Taler coins and spend them to pay for the order we just created. + +In practice, you will rarely if ever setup orders manually like this. Instead, +a `GNU Taler e-commerce front-end +<https://taler.net/en/docs.html#extensions>`_ or the +:ref:`taler-merchant-pos-app` will do this on-demand. Here, you will only need +to provide the respective front-ends with the URL of your instance +(e.g. ``https://backend.$DOMAIN/instances/$NAME``) and your access token. + .. _Secure-setup: @@ -867,11 +978,12 @@ Secure setup .. index:: security .. index:: TLS -The Taler backend does not include even the most basic forms of access control -or transport layer security. Thus, production setups **must** deploy the -Taler backend behind an HTTP(S) server that acts as a *reverse proxy*, -performs TLS termination and authentication and then forwards requests to the -backend. +The Taler backend is deliberately simple in terms of support for access +control or transport layer security (TLS). Thus, production setups **must** +deploy the Taler backend behind an HTTP(S) server that acts as a *reverse +proxy*, performs TLS termination and authentication and then forwards requests +to the backend. + Using UNIX domain sockets ------------------------- @@ -996,15 +1108,83 @@ Legal conditions for using the service .. include:: frags/legal.rst +.. _MerchantTemplateCustomization: -Mustach HTML Templates +Template Customization ---------------------- -The installation process will install various HTML templates to be served -to trigger the wallet interaction. You may change those templates to your -own design. The templating language used is Mustach, and the templates -are in the ``share/taler/merchant/templates/`` directory. +The installation process will install various HTML templates to be served to +trigger the wallet interaction. You may change those templates to your own +design. The templating language used is `Mustach +<https://gitlab.com/jbol/mustach>`__, and the templates are in the +``share/taler/merchant/templates/`` directory. + +The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the +name of the template and ``$LANG`` is the 2-letter language code of the +template. English templates must exist and will be used as a fallback. If the +browser (user-agent) has provided language preferences in the HTTP header and +the respective language exists, the correct language will be automatically +served. + +The following subsections give details about each of the templates. The +subsection titles are the ``$NAME`` of the respective template. + +request_payment +^^^^^^^^^^^^^^^ + +Page shown to request the user to make a payment. + +This template is instantiated using the following information: + + * taler_pay_uri: String; the ``taler://pay/`` URI that must be given + to the wallet to initiate the payment + + * taler_pay_qrcode_svg: Image; an SVG image of the QR code with the + ``taler_pay_uri``. + + * order_summary: String; a text summarizing the order + + * order_status_url: URL of the merchant backend where the order status + can be found, useful for long-polling to check if the order has been paid + + +offer_refund +^^^^^^^^^^^^ + +Page shown to offer a customer a refund. + +This template is instantiated using the following information: + + * taler_refund_uri: String; the ``taler://pay/`` URI that must be given + to the wallet to initiate the payment + + * taler_refund_qrcode_svg: Image; an SVG image of the QR code with the + ``taler_pay_uri``. + * refund_amount: Amount; how much did the merchant refund + + * refund_taken: Amount; how much did the customer already take back in refunds + + * order_summary: String; a text summarizing the order + + + +show_order_details +^^^^^^^^^^^^^^^^^^ + +Page shown to the user when they go back to the payment page but +no payment is required and no refund is present. + +This template is instantiated using the following information: + + * order_summary: String; a text summarizing the order + + * contract_terms: Object; the full contract terms (shoud probably + not be shown in full!) + + * refund_amount: Amount; how much did the merchant refund + + * refund_taken: Amount; how much did the customer already take back in refunds Static files ------------ @@ -1131,6 +1311,7 @@ runtime by the setup logic provided by ``taler-unified-setup.sh``. See :ref:`Taler Exchange Manual <Benchmark-choose-bank>` for how to use ``taler-unified-setup.sh`` to setup the system and in particular on how to specify the bank to be used. + Running taler-merchant-benchmark ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1167,8 +1348,10 @@ second gives the chance to leave some payments unaggregated, and also to 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 back-office facility. +.. note:: + + The ability to drive the aggregation policy is useful for testing + the back-office facility. Any subcommand is also equipped with the canonical ``--help`` option, so feel free to issue the following command in order to explore all the @@ -1195,9 +1378,6 @@ option: - - - Temporarily Abandoned Features ============================== |