diff options
Diffstat (limited to 'taler-user-guide.rst')
| -rw-r--r-- | taler-user-guide.rst | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/taler-user-guide.rst b/taler-user-guide.rst new file mode 100644 index 00000000..8e42c0d2 --- /dev/null +++ b/taler-user-guide.rst @@ -0,0 +1,328 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2023 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Christian Grothoff + + +User Guide +########## + +.. contents:: Table of Contents + :depth: 1 + :local: + +Introduction +============ + +About GNU Taler +--------------- + +.. include:: frags/about-taler.rst + + +About this guide +---------------- + +This guide explains various ways how users can interact with a GNU Taler +installation. It assumes that a bank, exchange and merchant backend are +running and that the user has a GNU Taler wallet installed is able to create +an account at the bank. Some operations also require access to the merchant +backend. + + +Withdrawing from bank accounts +============================== + +Withdrawing is the step where money is moved from a bank account into +a GNU Taler wallet. There are two main ways to do this. + +Bank integrated withdrawal +-------------------------- + +If the bank supports it, you can withdraw money into your GNU Taler wallet +directly from your banking app or online banking website. If supported, there +should be an option in your online banking to withdraw money to a GNU Taler +wallet. The bank should ask for the amount and then generate a QR code that +you need to scan with your GNU Taler wallet. Alternatively, if the +WebExtension wallet is installed, the bank website may directly switch to the +GNU Taler wallet. In the GNU Taler wallet, you may have to first confirm the +terms of service of the selected GNU Taler exchange. Afterwards, applicable +fees will be shown and you will be given the option to accept the withdrawal. +Next, you need to authorize the withdraw operation in the bank. If possible, +the GNU Taler wallet may automatically switch to the bank's website, it is +also possible that you have to go back to the banking app explicitly. After +authorizing the withdraw operation, you will have to wait a bit for the money +to be wired to the exchange. Depending on the banking system, this can take +anywhere from a few seconds to many hours. Afterwards, the money will show up +in your wallet. + +Wallet initiated withdrawal +--------------------------- + +In this case, you will start the withdraw process from the GNU Taler wallet. +Under "Settings", you will find a list of exchanges. If the list is empty or +does not contain the desired exchange, you may have to first add the exchange +by providing the respective URL. The payment service provider operating the +exchange service should have such a QR code on their Web site. + +Next to the exchange, there is a drop-down menu with an option to "withdraw". +(If you already have money in your wallet, you will also find the same button +when viewing the transaction history of the respective currency.) The wallet +will ask you to enter the amount to withdraw and accept the terms of service +and to pay the applicable fees (if any). Afterwards, the wallet will give you +wire instructions, telling you which amount to wire to which bank account. +Most importantly, the wallet will give you a wire transfer subject that must +be specified for the wire transfer. If you make a typo in the subject, the +wallet will not be topped up and the exchange will send the money back to your +bank account eventually (possibly minus a fee). Simply make the wire transfer +as instructed by the wallet. Once the money has arrived at the exchange, the +wallet will automatically withdraw the funds. + + +Depositing into bank accounts +============================= + +If you have money in your wallet, you can use the "deposit" button to deposit +the funds into a bank account. The wallet will ask you to specify the amount +and the target bank account. + + +Sending digital cash +==================== + +Once you have digital cash, you can send it to another GNU Taler +wallet. Simply specify the amount and a human-readable reason for the +transfer. The wallet will then show a QR code (and give the option to export +the payment as a taler://-URL). Send the image of the QR code to the +receiving wallet (or send the taler://-URL securely to the target wallet). + +The target wallet should scan the QR code (or enter the text of the +taler://-URL into the URL import dialog which is available by holding or +clicking the QR code scan button). Afterwards, review the reason text and +accept the funds to complete the transaction. + + +Receiving digital cash +====================== + +To receive funds from another user, you can send a payment request to another GNU +Taler wallet. Simply specify the amount and a human-readable reason for the +payment request. The wallet will then show a QR code (and give the option to export +the payment request as a taler://-URL). Send the image of the QR code to the payer +wallet (or send the taler://-URL to the target wallet). + +The target wallet should scan the QR code (or enter the text of the +taler://-URL into the URL import dialog which is available by holding or +clicking the QR code scan button). Afterwards, review the reason for +the payment request and decide whether or not to pay it. Selecting +"pay" will complete the transaction. + +Depending on the configuration of the exchange, the receiving wallet may have +to undergo some KYC check before the funds are actually released to the +receiver. + + +.. index:: instance +.. _Instance-account-configuration: + +Configuring Accounts at a Merchant Instance +=========================================== + +Before you can setup a merchant instance, you need somebody to operate a +`Taler Merchant Backend <taler-merchant-backend-operator-manual>`_ and `grant +you access to an instance <Instance-setup>`_ at that backend. For this, you +should receive the base URL of the instance and an access token. + +The main configuration data that must be provided for each instance +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://``-URI. +See `RFC 8905 <https://tools.ietf.org/html/rfc8905>`_ +for the format of ``payto://``-URIs. Note that the "receiver-name" is +optional in RFC 8905 but mandatory in GNU Taler. + +For first tests, you may want to sign up for a KUDOS bank account at +`https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_. In this case, +the ``payto://``-URI will be of the form +``payto://iban/$IBAN?receiver-name=$NAME`` where ``$IBAN`` must be replaced +with the IBAN shown on the main page of the account shown at +`https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_ after logging +in. + +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 actual 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?receiver-name=$NAME`` where ``$IBAN`` must be replaced +with the actual IBAN number and ``$NAME`` with your actual name. Make sure to +URI-encode your name. The merchant SPA will do this automatically when you +use it to configure the bank account. + + + +Using the Point-of-Sale App +=========================== + +A simple way for merchants to accept GNU Taler payments is the use of the +point-of-sale app. The app can be installed on an Android phone or tablet +and is configured via a simple JSON file on a Web site: + +* In the app settings you need to specify the URL of the Web site where + the app can download the categories, products and prices from which + orders are to be compiled. You can optionally specify a username and + password to authenticate to the Web server. + +* The syntax of the JSON file is described in the point-of-sale app + manual. However, you may simply want to download the sample JSON + file from our documentation and use it as a starting point. + +* A key option is the merchant backend with the authorization key + which must be included in this JSON configuration. You may point + the point-of-sale app to any instance of a merchant backend. + +Once configured, the point-of-sale app allows the user to select a product +category and then to quickly add products from that category to an order. You +can easily edit the order, and finally use the "complete" button to generate a +QR code. The QR code must then be scanned by the GNU Taler wallet to initiate +the payment. Multiple orders can be entered concurrently, for example in a +restaurant where multiple tables are waited on at the same time. + + +Setting up an order in the merchant backoffice SPA +================================================== + +Arbitrary orders can also be created manually using the Web interface of +the GNU Taler merchant backend. For this, log into the single page app (SPA) +of the merchant backend using the authorization token of the respective +instance you want to use. + +You can then set up orders by providing all of the required fields of an +order, in particular an order summary and a price. You can also set various +optional fields or override instance default settings. + +When the order has been setup, you can follow a link to the payment page +which will show the QR code (and/or URL) that a GNU Taler wallet would need +to receive to initiate the payment process. The order status page also +shows you the progress of the order, including when a wallet has made the +payment. You can also use the backend to approve refunds. + + +Paying an order +=============== + +The payer simply scans the (dynamic) QR code to initiate the payment. If a +website is interacting with a WebExtension wallet, it may also directly +trigger the GNU Taler wallet without requiring the user to explicitly scan the +QR code. The payer should now review the contract terms and applicable fees. +Selecting "pay" will complete the transaction. Typically, the wallet will +then redirect the user to the fulfillment page where they can track the order +or directly view the digital product that they purchased. + + +Setting up a template +===================== + +A template provides all or part of the information needed to setup an order +and allows GNU Taler wallets to create an order. Usually, the creation of +orders is a privileged process that requires knowledge of the authorization +code for the respective instance. With templates, a customer's wallet can +directly create an order on-demand. The information of a template can be +partial, in which case the customer is expected to provide the remaining +details, typically the summary and/or amount of the order. + +When setting up a template you need to specify all of the fixed inputs that +the customer cannot change. You can then generate a template QR code where +you may additionally specify editable defaults for the order, such as a +default summary or a default amount which may still be changed by the wallet. +The resulting template QR code encodes the specific merchant backend, instance +and template ID as well as the (editable) default values. The resulting +static QR code can then be printed and put on display. + +Customers can scan the QR code with their GNU Taler wallet, complete the +missing details or edit the defaults (if any), and pay the resulting order. + +To secure template-based payments, you may specify a TOTP secret as part of +the template. In this case, the merchant backend will send a set of TOTP +payment confirmation codes to the GNU Taler wallet upon receiving a payment +for an order created based on the template. If the point-of-sale has a TOTP +generator with the same secret, they can compare their TOTP code with the +codes shown by the customer on their wallet. This provides additional +assurance that the customer actually made the payment instead of just showing +a fake confirmation screen. + + +Paying with static QR codes +=========================== + +The payer simply scans the (static) QR code to initiate the payment. If the +template does not specify a fixed amount, the payer will be prompted to enter +the amount to be paid (and possibly given the opportunity to specify or alter +the summary). Selecting "pay" will complete the transaction. If payment +confirmations are configured by the merchant backend, the wallet will then +display a TOTP confirmation code that can be shown to the merchant as a proof +of payment. + + + +Setting up a webhook +==================== + +To receive notifications when a purchase has been made or a refund was given +to a wallet, you can set up webhooks in the GNU Taler merchant backend. +Webhooks allow you to trigger HTTP(S) requests based on certain events. A +webhook is thus simply an HTTP request that the GNU Taler merchant backend +will make when a certain event (such as a payment) happens. + +There are various providers that can send an SMS to a phone number based on an +HTTP request. Thus, by configuring such a provider in a webhook you can +receive an SMS notification whenever a customer makes a payment. + +Webhooks are configured per instance. In the Webhook configuration, +you can specify which URL, which HTTP headers, which HTTP method and what HTTP +body to send to the Webhook. Webhooks are automatically retried (with +increasing delays) when the target server returns a temporary error. + +`Mustach templates <https://mustache.github.io/mustache.5.html>`__ are used +when defining the contents of Webhooks. Depending on the triggering event, +the templates will be expanded with event-specific data. + + +Pay events +---------- + +For "pay" events, the backend will provide the following +information to the Mustach templating engine: + +* :ref:`contract_terms <contract-terms>`: the contract terms of the paid order +* order_id: the ID of the order that received the refund + + +Refund events +------------- + +For "refund" events, the backend will provide the following information to the +Mustach templating engine: + +* timestamp: time of the refund (in nanoseconds since 1970) +* order_id: the ID of the order that received the refund +* :ref:`contract_terms <contract-terms>`: the full JSON of the contract terms of the refunded order +* refund_amount: the amount that was being refunded +* reason: the reason entered by the merchant staff for granting the refund; + be careful, you probably want to inform your staff if a webhook may expose + this information to the consumer |