diff options
| -rw-r--r-- | core/api-bank-sandbox.rst | 2 | ||||
| -rw-r--r-- | core/api-common.rst | 4 | ||||
| -rw-r--r-- | core/api-exchange.rst | 2 | ||||
| -rw-r--r-- | core/index.rst | 1 | ||||
| -rw-r--r-- | demo-deployment.rst | 10 | ||||
| -rw-r--r-- | taler-exchange-manual.rst | 2 | ||||
| -rw-r--r-- | taler-merchant-manual.rst | 94 |
7 files changed, 70 insertions, 45 deletions
diff --git a/core/api-bank-sandbox.rst b/core/api-bank-sandbox.rst index f490cabf..0c8ba190 100644 --- a/core/api-bank-sandbox.rst +++ b/core/api-bank-sandbox.rst @@ -57,7 +57,7 @@ For brevity, the list of response statuses for each endpoint may not be exhausti The following endpoints are served under ``/demobanks/default/circuit-api``. The client side of this API is offered both along the -:doc:`CLI <circuit-cli-commands>` and the SPA. The SPA is generally served +:doc:`CLI <../libeufin/circuit-cli-commands>` and the SPA. The SPA is generally served along Sandbox ``/`` path. Accounts diff --git a/core/api-common.rst b/core/api-common.rst index 8de555dd..d7c2d445 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -18,7 +18,7 @@ .. _http-common: -================================= +================================== Conventions for Taler RESTful APIs ================================== @@ -186,6 +186,8 @@ Examples: to decide whether it will talk to the service. +.. _error-codes: + ----------- Error Codes ----------- diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 1b6e5ddf..04c7cfd4 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -121,7 +121,7 @@ possibly by using HTTPS. // Set to true if this exchange allows the use // of reserves for tipping. - tipping_allowed: bool; + tipping_allowed: boolean; // EdDSA master public key of the exchange, used to sign entries // in ``denoms`` and ``signkeys``. diff --git a/core/index.rst b/core/index.rst index ae727016..d9ffa429 100644 --- a/core/index.rst +++ b/core/index.rst @@ -41,6 +41,7 @@ protocols using JSON. ../wallet/wallet-core api-auditor api-sync + api-challenger api-taldir api-mailbox api-bank diff --git a/demo-deployment.rst b/demo-deployment.rst deleted file mode 100644 index 2f0b5a04..00000000 --- a/demo-deployment.rst +++ /dev/null @@ -1,10 +0,0 @@ -This document explains how to install Taler+LibEuFin -on gv.taler.net, for demo.taler.net. - -1. Login as the ``demo`` user on ``gv.taler.net``. -2. Pull the latest ``deployment.git`` code. -3. Navigate to the ``deployment.git/docker/demo`` directory. -4. The README file is the reference about building and running the services. - -Nginx is already configured to reach the services as exported by -Docker Compose. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index e5b469b3..750be35a 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1126,7 +1126,7 @@ assign an identifier for the ``$FACADE_NAME`` below: $CONNECTION_NAME \ $LOCAL_ACCOUNT_NAME -At this point, the additional :doc:`taler-wire-gateway API <core/api-wire>` +At this point, the additional :doc:`taler-wire-gateway API <core/api-bank-wire>` becomes offered by the Nexus. The purpose is to let a Taler exchange rely on Nexus to manage its bank account. diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index a8dfd0e9..a12b1d7e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -44,11 +44,11 @@ Architecture overview .. index:: KUDOS Taler is a pure payment system, not a new crypto-currency. As such, it -operates in a traditional banking context. In particular, this means -that in order to receive funds via Taler, the merchant must have a -regular bank account, and payments can be executed in ordinary -currencies such as USD or EUR. For testing purposes, Taler uses a -special currency “KUDOS” and includes its own special bank. +operates in a traditional banking context. In particular, this means that in +order to receive funds via Taler, the merchant must have a regular bank +account, and payments can be executed in ordinary currencies such as USD or +EUR. Taler can also be used as a regional currency; for such scenarios, the +Taler system also includes its own stand-alone bank. .. index:: frontend .. index:: back-office @@ -56,8 +56,7 @@ special currency “KUDOS” and includes its own special bank. .. index:: DBMS .. index:: PostgreSQL -The Taler software stack for a merchant consists of four main -components: +The Taler software stack for a merchant consists of four main components: - A *frontend* which interacts with the customer’s browser. The frontend enables the customer to build a shopping cart and place an order. @@ -95,13 +94,13 @@ Taler exchange over the Internet. The frontend accesses the backend via a RESTful API. As a result, the frontend never has to directly communicate with the exchange, and also does not deal with sensitive data. In particular, the merchant’s signing keys and bank account information are encapsulated within -the Taler backend. +the Taler merchant backend. A typical deployment will additionally include a full-blown Web server (like Apache or Nginx). Such a Web server would be responsible for TLS termination and access control to the ``/private/`` and ``/management/`` API endpoints of the -merchant backend. Please carefully review the section on :ref:`Secure setup -<Secure-setup>` before deploying a Taler merchant backend to production. +merchant backend. Please carefully review the section on :ref:`secure setup +<Secure-setup>` before deploying a Taler merchant backend into production. Terminology @@ -114,21 +113,44 @@ Instances .. index:: instance -The backend allows the user to run multiple *instances* of shops with distinct -business entities sharing a single backend. Each instance uses its own bank -accounts and key for signing contracts. All major accounting functionality is -separate per instance. What is shared is the database, HTTP(S) address and -the main Taler configuration (accepted currency, exchanges and auditors). +The backend allows a single HTTP server to support multiple independent shops +with distinct business entities sharing a single backend. An *instance* is +the name or identifier that allows the single HTTP server to determine which +shop a request is intended for. Each instance has its own base URL in the +REST API of the merchant backend (``/instances/$INSTANCE/``). Each instance +can use its own bank accounts and keys for signing contracts. All major +accounting functionality is separate per instance. Access to each instance is +controlled via a bearer token (to be set in the HTTP "Authorization" header). +All instances share the same *database*, top-level HTTP(S) address and the +main Taler configuration (especially the accepted *currency* and *exchanges*). -Accounts --------- + .. note:: + + This documentation does not use the term "user" or "username" in + conjunction with instances as that might create confusion between + instances with paying customers using the system. We also do not use the + term "account" in conjunction with instances, as that might cause + confusion with bank accounts. That said, conceptually it is of course + acceptable to consider instances to be the "users" or "accounts" of a + merchant backend and the bearer token is equivalent to a passphrase. -.. index:: account + +Instance Bank Accounts +---------------------- + +.. index:: instance-bank-account To receive payments, an instance must have configured one or more bank -*accounts*. The backend does not have accounts for users, and instances are -also not really 'accounts'. So whenever we use the term *account*, it is about -a bank account of a merchant. +*accounts*. When configuring the bank account of an instance, one should +ideally also provide the address and credentials of an HTTP service +implementing the `Taler Bank Merchant HTTP API +<taler-bank-merchant-http-api>`_. Given such a service, the GNU Taler +merchant backend can automatically reconcile wire transfers from the +exchange to the merchant's bank account with the orders that are being +settled. + +This documentation exclusively uses the term *account* for the bank +accounts of a merchant or shop that may be associated with an instance. Inventory --------- @@ -141,21 +163,26 @@ Inventory The Taler backend offers inventory management as an optional function. Inventory is tracked per instance and consists of *products* sold in -*units*. Inventory can be finite or infinite (for digital products). -Products may include previews (images) to be shown to the user and other -meta-data. Inventory management allows the frontend to *lock* products, -reserving them for a particular (unpaid) *order*. The backend can keep -track of how many units of a product remain in stock and ensure that -the number of units sold does not exceed the number of units in stock. +*units*. Inventory can be finite (physical stock) or infinite (for digital +products). Products may include previews (images) to be shown to the user as +well as other meta-data. Inventory management allows the frontend to *lock* +products, reserving a number of units from stock for a particular (unpaid) +*order*. The backend can keep track of how many units of a product remain in +stock and ensure that the number of units sold does not exceed the number of +units in stock. Inventory management is optional, and it is possible for the frontend to -include products in orders that are not in the inventory, or to override -prices of products in the inventory. +include products in orders that are not in the inventory. The frontend +can also override prices of products in the inventory or set a total price +for an order that is different from the price of the sum of the products +in the order. + Orders and Contracts -------------------- .. index:: order +.. index:: terms .. index:: contract .. index:: claim .. index:: pay @@ -164,8 +191,13 @@ Orders and Contracts .. index:: lock .. index:: legal expiration -In Taler, users pay merchants for orders. An order is first created by the -merchant, where the merchant specifies the specific terms of the order. +In Taler, users pay merchants for *orders*. An order is first created by the +merchant. To create an order, the merchant must specify the specific *terms* +of the order. Order *terms* include details such as the total amount to be +paid, payment fees the merchant is willing to cover, the set of products to +deliver, a delivery location and many other details. The `merchant API +specification <contract-terms>`_ specifies the full set of possible order +terms. After an order is created, it is *claimed* by a wallet. Once an order is claimed by a specific wallet, only that wallet will be able to pay for this |