2. User Guide¶
2.1. Introduction¶
2.1.1. About GNU Taler¶
GNU Taler is an open protocol for an electronic payment system with a free software reference implementation. GNU Taler offers secure, fast and easy payment processing using well understood cryptographic techniques. GNU Taler allows customers to remain anonymous, while ensuring that merchants can be held accountable by governments. Hence, GNU Taler is compatible with anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as data protection regulation (such as GDPR).
2.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.
2.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.
2.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.
2.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.
2.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.
2.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.
2.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.
2.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.
2.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.
2.8. 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.
2.9. 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.
2.10. 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.
2.11. 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.
2.12. 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 and limited version of it are used when defining the contents of Webhooks. Depending on the triggering event, the templates will be expanded with event-specific data. Limited in this case means that only a specific string is being replaced with the event-specific data, no support for parsing conditions or nested structures is provided.
2.12.1. Order pay events¶
For “pay” events, the backend will provide the following information to the Mustache templating engine:
contract_terms: the contract terms of the paid order.
order_id: the ID of the order that received the refund.
2.12.2. Order refund events¶
For “refund” events, the backend will provide the following information to the Mustache 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_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.
2.12.3. Order settled events¶
For “order_settled” events, the backend will provide the following information to the limited Mustache templating engine:
order_id: The unique identifier of the order that has been fully settled (all payments completed and wired to the merchant).
2.12.4. Category added events¶
For “category_added” events, the backend will provide the following information to the limited Mustache templating engine:
webhook_type: “category_added”.
category_serial: The unique identifier of the newly added category.
category_name: The name of the newly added category.
merchant_serial: The unique identifier of the merchant associated with the category.
2.12.5. Category updated events¶
For “category_updated” events, the backend will provide the following information to the limited Mustache templating engine:
webhook_type: “category_updated”.
category_serial: The unique identifier of the updated category.
old_category_name: The name of the category before the update.
category_name: The name of the category after the update.
category_name_i18n: The internationalized name of the category after the update.
old_category_name_i18n: The internationalized name of the category before the update.
2.12.6. Category deleted events¶
For “category_deleted” events, the backend will provide the following information to the limited Mustache templating engine:
webhook_type: “category_deleted”.
category_serial: The unique identifier of the deleted category.
category_name: The name of the deleted category.
2.12.7. Inventory added events¶
For “inventory_added” events, the backend will provide the following information to the limited Mustache templating engine:
webhook_type: “inventory_added”.
product_serial: The unique identifier of the newly added product.
product_id: The ID of the newly added product.
description: The description of the newly added product.
description_i18n: The internationalized description of the newly added product.
unit: The unit of the newly added product.
image: The image of the newly added product.
taxes: The taxes of the newly added product.
price: The price of the newly added product.
total_stock: The total stock of the newly added product.
total_sold: The total sold of the newly added product.
total_lost: The total lost of the newly added product.
address: The address of the newly added product.
next_restock: The next restock of the newly added product.
minimum_age: The minimum age for buying the newly added product.
2.12.8. Inventory updated events¶
For “inventory_updated” events, the backend will provide the following information to the limited Mustache templating engine:
webhook_type: “inventory_updated”.
product_serial: The unique identifier of the updated product.
product_id: The ID of the product.
old_description: The description of the product before the update.
description: The description of the product after the update.
old_description_i18n: The internationalized description of the product before the update.
description_i18n: The internationalized description of the product after the update.
old_unit: The unit of the product before the update.
unit: The unit of the product after the update.
old_image: The image of the product before the update.
image: The image of the product after the update.
old_taxes: The taxes of the product before the update.
taxes: The taxes of the product after the update.
old_price: The price of the product before the update.
price: The price of the product after the update.
old_total_stock: The total stock of the product before the update.
total_stock: The total stock of the product after the update.
old_total_sold: The total sold of the product before the update.
total_sold: The total sold of the product after the update.
old_total_lost: The total lost of the product before the update.
total_lost: The total lost of the product after the update.
old_address: The address of the product before the update.
address: The address of the product after the update.
old_next_restock: The next restock of the product before the update.
next_restock: The next restock of the product after the update.
old_minimum_age: The minimum age for buying the product before the update.
minimum_age: The minimum age for buying the product after the update.
2.12.9. Inventory deleted events¶
For “inventory_deleted” events, the backend will provide the following information to the limited Mustache templating engine:
webhook_type: “inventory_deleted”.
product_serial: The unique identifier of the deleted product.
product_id: The ID of the deleted product.
description: The description of the deleted product.
description_i18n: The internationalized description of the deleted product.
unit: The unit of the deleted product.
image: The image of the deleted product.
taxes: The taxes of the deleted product.
price: The price of the deleted product.
total_stock: The total stock of the deleted product.
total_sold: The total sold of the deleted product.
total_lost: The total lost of the deleted product.
address: The address of the deleted product.
next_restock: The next restock of the deleted product.
minimum_age: The minimum age for buying the deleted product.