diff options
Diffstat (limited to 'taler-user-guide.rst')
| -rw-r--r-- | taler-user-guide.rst | 194 |
1 files changed, 45 insertions, 149 deletions
diff --git a/taler-user-guide.rst b/taler-user-guide.rst index e685ede4..127218fb 100644 --- a/taler-user-guide.rst +++ b/taler-user-guide.rst @@ -16,8 +16,12 @@ @author Christian Grothoff -GNU Taler User Guide -#################### +User Guide +########## + +.. contents:: Table of Contents + :depth: 1 + :local: Introduction ============ @@ -38,8 +42,8 @@ an account at the bank. Some operations also require access to the merchant backend. -Withdrawing -=========== +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. @@ -70,7 +74,8 @@ 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. +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 @@ -86,16 +91,16 @@ as instructed by the wallet. Once the money has arrived at the exchange, the wallet will automatically withdraw the funds. -Depositing -========== +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 cash -============ +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 @@ -109,19 +114,19 @@ clicking the QR code scan button). Afterwards, review the reason text and accept the funds to complete the transaction. -Invoicing -========= +Receiving digital cash +====================== -To receive funds from another user, you can send an invoice to another GNU +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 -invoice. The wallet will then show a QR code (and give the option to export -the invoice as a taler://-URL). Send the image of the QR code to the payer +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 invoice and decide whether or not to pay the invoice. Selecting +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 @@ -178,18 +183,18 @@ 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. +* 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. +* 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. +* 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 @@ -270,9 +275,8 @@ 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 confirmation code that can be shown to the merchant as a proof of -payment. - +display a TOTP confirmation code that can be shown to the merchant as a proof +of payment. @@ -294,9 +298,10 @@ 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 are used when defining the contents of Webhooks. Depending -on the triggering event, the templates will be expanded with event-specific -data. +`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 ---------- @@ -304,8 +309,8 @@ Pay events For "pay" events, the backend will provide the following information to the Mustach templating engine: - * contract_terms: the contract terms of the paid order - * order_id: the ID of the order that received the refund +* :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 @@ -314,119 +319,10 @@ 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 - * contract_terms: the full JSON of the contract terms of the refunded order - * refund_amout: 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 - - -.. _Rewarding-visitors: - -Rewarding visitors -================== - -.. index:: rewards - -Taler can also be used to reward digital cash to Web site visitors. For -example, you may be running an online survey, and you want to reward those -people that have dutifully completed the survey. If they have installed a -Taler wallet, you can provide them with a reward for their deeds. This section -describes how to setup the Taler merchant backend for rewarding. - -There are three basic steps that must happen to reward a visitor. - -.. _Fund-the-reserve: - -Fund the reserve ----------------- - -.. index:: reserve - -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: - -.. code-block:: console - - $ taler-merchant-setup-reserve \ - -a KUDOS:10 \ - -e https://exchange.demo.taler.net/ \ - -m http://localhost:8888/instances/default - -The above command assumes that the merchant runs on localhost on -port 8888. -For more information, including how to transmit authentication information -to the backend, see :doc:`manpages/taler-merchant-setup-reserve.1`. - -The command will output a ``payto://`` URI which specifies where to -wire the funds and which wire transfer subject to use. - - .. note:: - - FIXME: add full example output. - -In our example, the output for the wire transfer subject is: - -.. code-block:: none - - QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG - -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 -“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 -rewarding. - -Note that an exchange will typically close a reserve after four weeks, wiring -all remaining funds back to the sender’s account. Thus, you should plan to -wire funds corresponding to a campaign of about two weeks to the exchange -initially. If your campaign runs longer, you should setup another reserve -every other week to ensure one is always ready. - -.. _Authorize-a-reward: - -Authorize a reward ------------------- - -When your frontend has reached the point where a client is supposed to receive -a reward, it needs to first authorize the reward. For this, the frontend must use -a POST to ``/private/reserves/$RESERVE_PUB/authorize-reward``. To authorize a -reward, the frontend has to provide the following information in the body of the -POST request: - -- The amount of the reward - -- The justification (only used internally for the back-office) - -- The URL where the wallet should navigate next after the reward was - processed - -- The reward-pickup URL (see next section) - -In response to this request, the backend will return a reward token, an -expiration time and the exchange URL. The expiration time will indicate -how long the reward is valid (when the reserve expires). The reward token is -an opaque string that contains all the information needed by the wallet -to process the reward. The frontend must send this reward token to the browser -in a special “402 Payment Required” response inside the ``Taler`` -header. - -The frontend should handle errors returned by the backend, such as -misconfigured instances or a lack of remaining funds for rewarding. - -.. _Picking-up-of-the-reward: - -Picking up of the reward ------------------------- - -The wallet will POST a JSON object to the shop’s -``/rewards/$REWARD_ID/pickup`` handler. -The frontend must then forward this request to the backend. The response -generated by the backend can then be forwarded directly to the wallet. +* 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_amout: 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 |