path: root/taler-user-guide.rst

GNU Taler User 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
===========

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.

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 charged 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
==========

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
============

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.


Invoicing
=========

To receive funds from another user, you can send an invoice 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
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
"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.


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 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, you can set up
webhooks in the GNU Taler merchant backend.  A webhook is simply an HTTP
request that the GNU Taler merchant backend will make when a certain event
(usually 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 at a particular instance.