User Guide

1.1. User Guide#

1.1.1. Introduction#

1.1.1.1. About GNU Taler#

1.1.1.2. 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.

1.1.2. 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.

1.1.2.1. 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.

1.1.2.2. 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.

1.1.3. 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.

1.1.4. 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.

1.1.5. 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.

1.1.6. Configuring Accounts at a Merchant Instance#

Before you can setup a merchant instance, you need somebody to operate a Taler Merchant Backend and grant you access to an instance 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 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/. 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/ 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.

1.1.7. 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.