diff options
| -rw-r--r-- | index.rst | 1 | ||||
| -rw-r--r-- | taler-bank-manual.rst | 4 | ||||
| -rw-r--r-- | taler-merchant-api-tutorial.rst | 8 | ||||
| -rw-r--r-- | taler-merchant-manual.rst | 2 | ||||
| -rw-r--r-- | taler-nfc-guide.rst | 46 | ||||
| -rw-r--r-- | taler-wallet.rst | 74 |
6 files changed, 120 insertions, 15 deletions
@@ -53,6 +53,7 @@ Documentation Overview core/index taler-exchange-manual taler-merchant-manual + taler-wallet taler-nfc-guide.rst taler-merchant-api-tutorial taler-bank-manual diff --git a/taler-bank-manual.rst b/taler-bank-manual.rst index c85e0aa4..4c1b5730 100644 --- a/taler-bank-manual.rst +++ b/taler-bank-manual.rst @@ -1,5 +1,5 @@ -The GNU Taler bank manual -######################### +GNU Taler bank manual +##################### Introduction ============ diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 2981e430..bfae7f02 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -1,4 +1,4 @@ -The GNU Taler Merchant API Tutorial +GNU Taler Merchant API Tutorial ################################### Introduction @@ -27,8 +27,6 @@ This version of the tutorial has examples for Python3. It uses the requests library for HTTP requests. Versions for other languages/environments are available as well. -examples -git If you want to look at some simple, running examples, check out these: - The `essay @@ -346,7 +344,6 @@ Advanced topics Detecting the Presence of the Taler Wallet ------------------------------------------ -wallet Taler offers ways to detect whether a user has the wallet installed in their browser. This allows Web sites to adapt accordingly. Note that not all platforms can do presence detection reliably. Some platforms might @@ -504,9 +501,6 @@ previous payment. The Taler Order Format ---------------------- -contract -terms -order A Taler order can specify many details about the payment. This section describes each of the fields in depth. diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index d668de35..1dfbfc70 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1,5 +1,5 @@ GNU Taler Merchant Backend Operator Manual -############################################## +########################################## Introduction ============ diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst index f9646742..029b84f4 100644 --- a/taler-nfc-guide.rst +++ b/taler-nfc-guide.rst @@ -23,10 +23,28 @@ The following steps show a simple payment process with GNU Taler. Examples are written in `Bash <https://www.gnu.org/software/bash/>`_ syntax, using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. + 1. The merchant creates an *order*, which contains the details of the payment and the product/service that the customer will receive. An order is identified by an alphanumeric *order ID*. + The *fulfillment URL* is an URL that the wallet will redirect the customer + to once the payment is complete. For digital products, this is typically an + ``https(s)://`` URL that renders the purchased content. For physical + products and in-store purchases, a ``taler://fulfillment-success/<message>`` + URL should be specified instead. The wallet will display the URL-encoded + UTF-8 text ``<message>`` when the payment has succeeded. + + .. hint:: + + When an ``http(s)://`` URL is used as the fulfillment URL in an in-store / NFC payment, + the user might not be able to view the page, as request tunneling only works for requests + made by the wallet to the merchant backend / exchange. + + In these situations, wallets should display to the user that a page to view the purchase + can be opened, and give a warning if it is detected that the devices does not have Internet + connectivity. + The following :http:post:`/order` request to the merchant backend creates a simple order: @@ -77,7 +95,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. The details of ``taler://`` URIs are specified :ref:`here <taler-uri-scheme>`. 3. The wallet processes the ``taler://pay/`` URI. In this example, we use the - command line wallet: + command-line wallet: .. code-block:: sh @@ -90,6 +108,12 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. $ taler-wallet-cli pay-uri 'taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J' # [... User is asked to confirm the payment ...] + .. hint:: + + The command-line wallet is typically used by developers and not by end-users. + See the :ref:`wallet manual <command-line-wallet>` for installation instructions. + + 4. The merchant checks the payment status again: .. code-block:: sh @@ -104,6 +128,16 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. # ... (some fields omitted) } + .. note:: + + When paying for digital products displayed on a Web site identified by the + fulfillment URL, the merchant only needs to check the payment status + before responding with the fulfillment page. + + For in-store payments, the merchant must periodically check the payment status. + Instead of polling in a busy loop, the ``long_poll_ms`` parameter of :http:get:`/check-payment` + should be used. + Taler NFC Basics ================ @@ -126,7 +160,8 @@ During the time that the wallet is paired with a reader, there is state associated with the communication channel. Most importantly, the first message sent by the reader to the wallet must be a ``SELECT FILE (=0xA4)`` that selects the GNU Taler AID. Messages that are sent before the correct ``SELECT FILE`` -message result in undefined behavior. +message results in implementation-defined behavior, such as the tag disconnecting, +ignoring the message or an app other than the wallet receiving the message. The reader sends commands to the wallet with the ``PUT DATA (=0xDA)`` instruction, using the instruction parameters ``0x0100``, denoting a @@ -159,10 +194,11 @@ first byte. The rest of the body is interpreted depending on the TID. .. list-table:: - :widths: 5 50 + :widths: 15 50 :header-rows: 1 - * - TID (wallet to reader) + * - TID + (wallet to reader) - Description * - ``0x03`` - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling request. @@ -228,7 +264,7 @@ The request tunneling request/response JSON messages have the following schema: // Request headers headers?: { [name: string]: string }; - // JSON body for the request, only applicable to GET requests + // JSON body for the request, only applicable to POST requests body?: object; } diff --git a/taler-wallet.rst b/taler-wallet.rst new file mode 100644 index 00000000..50bf0ef9 --- /dev/null +++ b/taler-wallet.rst @@ -0,0 +1,74 @@ +GNU Taler Wallet Manual +####################### + +The GNU Taler wallet allows customers to withdraw and spend digital cash. + +.. _command-line-wallet: + +Command-line Wallet +=================== + +The command-line wallet is used primarily for testing by developers. + +Building from source +-------------------- + +.. code-block:: sh + + $ git clone https://git.taler.net/wallet-core.git + $ cd wallet-core + $ ./configure --prefix=$INSTALL_PREFIX + $ make && make install + +The wallet command-line interface should then be available as ``taler-wallet-cli`` under ``$INSTALL_PREFIX/bin``. + +Installation via NPM +-------------------- + +The wallet can also obtained via NPM, the Node Package Manager. + +To install the wallet as a global package, run: + +.. code-block:: sh + + $ npm install -g taler-wallet + # check if installation was successful + $ taler-wallet-cli --version + +To install the wallet only for your user, run: + +.. code-block:: sh + + $ npm install -g --prefix=$HOME/local taler-wallet + # check if installation was successful + $ taler-wallet-cli --version + # If this fails, make sure that $HOME/local/bin is in your $PATH + +To use the wallet as a library in your own project, run: + +.. code-block:: sh + + $ npm install taler-wallet + + +WebExtension Wallet +=================== + +Building from source +-------------------- + +.. code-block:: sh + + $ git clone https://git.taler.net/wallet-core.git + $ cd wallet-core + $ ./configure + $ make webex-stable + # Packaged extension now available as: + # dist/taler-wallet-$VERSION.zip + + +Android Wallet +============== + +*TODO* + |