diff options
-rw-r--r-- | libeufin/nexus-tutorial.rst | 4 | ||||
-rw-r--r-- | taler-exchange-manual.rst | 5 | ||||
-rw-r--r-- | taler-merchant-api-tutorial.rst | 57 |
3 files changed, 39 insertions, 27 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index c952a242..6b6eff67 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -143,6 +143,8 @@ core banking system with EBICS access to bank accounts. The sandbox relies on a database, which you must specify using a JDBC connection URI with the ``LIBEUFIN_SANDBOX_DB_CONNECTION`` environment variable, before invoking any commands. +(If this variable is not set, ``libeufin-sandbox`` complains and exits.) + Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TCP)* (e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``) are supported right now. @@ -238,6 +240,8 @@ Connect Nexus with an EBICS account Nexus relies on a database, which you must specify using a JDBC connection URI with the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment variable, before invoking any commands. +(If this variable is not set, ``libeufin-nexus`` complains and exits.) + Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TCP)* (e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``) are supported right now. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 5f0a6ab4..3424f991 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -496,6 +496,8 @@ must then have the following options: - ``DURATION_SPEND``: How long is a coin of the given type valid? Smaller values result in lower storage costs for the exchange. +- ``DURATION_LEGAL``: How long is the coin of the given type legal? + - ``FEE_WITHDRAW``: What does it cost to withdraw this coin? Specified using the same format as value. @@ -505,6 +507,9 @@ must then have the following options: - ``FEE_REFRESH``: What does it cost to refresh this coin? Specified using the same format as value. +- ``FEE_REFUND``: What does it cost to refund this coin? + Specified using the same format as value. + - ``RSA_KEYSIZE``: How many bits should the RSA modulus (product of the two primes) have for this type of coin. diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 2070a943..e4a9d151 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -49,7 +49,7 @@ This chapter explains some basic concepts. In the second chapter, you will learn how to do basic payments. This version of the tutorial has examples for Python3. It uses the -requests library for HTTP requests. Versions for other +``requests`` library for HTTP requests. Versions for other languages/environments are available as well. If you want to look at some simple, running examples, check out these: @@ -167,7 +167,7 @@ https://backend.demo.taler.net/: .. Note:: These are fictional merchants used for our demonstrators and not affiliated with or officially approved by the respective projects. -All endpoints for instances offer the same API. Thus, which instance is +All endpoints for instances offer the same API. Thus, which instance to be used is simply included in the base URL of the merchant backend. @@ -193,26 +193,26 @@ field: .. index:: summary .. index:: fulfillment URL -- amount: The amount to be paid, as a string in the format +- ``amount``: The amount to be paid, as a string in the format ``CURRENCY:DECIMAL_VALUE``, for example ``EUR:10`` for 10 Euros or ``KUDOS:1.5`` for 1.5 KUDOS. -- summary: A human-readable summary for what the payment is about. The +- ``summary``: A human-readable summary for what the payment is about. The summary should be short enough to fit into titles, though no hard limit is enforced. -- fulfillment_url: A URL that will be displayed once the payment is +- ``fulfillment_url``: A URL that will be displayed once the payment is completed. For digital goods, this should be a page that displays the product that was purchased. On successful payment, the wallet automatically appends the ``order_id`` as a query parameter, as well - as the ``session_sig`` for session-bound payments (discussed later). + as the ``session_sig`` for session-bound payments (discussed below). Orders can have many more fields, see `The Taler Order Format <#The-Taler-Order-Format>`__. When POSTing an order, you can also specify additional details such as an override for the refund duration and instructions for inventory management. These are rarely needed and not covered in this -tutorial; please read the :doc:`core/api-merchant` reference +tutorial; please see the :doc:`core/api-merchant` reference manual for details. A minimal Python snippet for creating an order would look like this: @@ -289,12 +289,12 @@ If the ``order_status`` field in the response is ``paid``, you will not get a ``payment_redirect_url`` and instead information about the payment status, including: -- contract_terms: The full contract terms of the order. +- ``contract_terms``: The full contract terms of the order. -- refunded: ``true`` if a (possibly partial) refund was granted for +- ``refunded``: ``true`` if a (possibly partial) refund was granted for this purchase. -- refunded_amount: Amount that was refunded +- ``refunded_amount``: Amount that was refunded Once the frontend has confirmed that the payment was successful, it usually needs to trigger the business logic for the merchant to fulfill @@ -302,7 +302,7 @@ the merchant’s obligations under the contract. .. Note:: You do not need to keep querying to notice changes - to the order's transaction status. The endpoint + to the order's transaction status. The endpoints support long polling, simply specify a ``timeout_ms`` query parameter with how long you want to wait at most for the order status to change to ``paid``. @@ -328,12 +328,12 @@ The frontend can instruct the merchant backend to authorize a refund by The refund request JSON object has only two fields: -- refund: Amount to be refunded. If a previous refund was authorized +- ``refund``: Amount to be refunded. If a previous refund was authorized for the same order, the new amount must be higher, otherwise the operation has no effect. The value indicates the total amount to be refunded, *not* an increase in the refund. -- reason: Human-readable justification for the refund. The reason is +- ``reason``: Human-readable justification for the refund. The reason is only used by the Back Office and is not exposed to the customer. If the request is successful (indicated by HTTP status code 200), the @@ -406,7 +406,7 @@ Note that changing the session ID to a different device requires the involvement of the wallet that made the payment, thus reasonably limiting the possibility of broadly sharing the digital purchases. Repurchase detection is also *only* done for HTTP(S) fulfillment URLs. In particular, this means -fulfillment URIs like "taler://fulfillment-success/$MESSAGE" are not +fulfillment URIs like ``taler://fulfillment-success/$MESSAGE`` are not considered to identify a resource you can pay for and thus do not have to be unique. @@ -442,24 +442,27 @@ funds available for tipping, query the ``/tip-query`` endpoint: ... headers={"Authorization": "ApiKey sandbox"}) <Response [200]> -authorize tip +.. _authorize-tip: + To authorize a tip, ``POST`` to ``/tip-authorize``. The following fields are recognized in the JSON request object: -- amount: Amount that should be given to the visitor as a tip. +- ``amount``: Amount that should be given to the visitor as a tip. -- instance: Merchant instance that grants the tip (each instance may +- ``instance``: Merchant instance that grants the tip (each instance may have its own independent tipping funds configured). -- justification: Description of why the tip was granted. Human-readable +- ``justification``: Description of why the tip was granted. Human-readable text not exposed to the customer, but used by the Back Office. -- next_url: The URL that the user’s browser should be redirected to by +- ``next_url``: The URL that the user’s browser should be redirected to by the wallet, once the tip has been processed. The response from the backend contains a ``tip_redirect_url``. The customer’s browser must be redirected to this URL for the wallet to pick -up the tip. pick up tip +up the tip. + +.. _pick-up-tip: This code snipped illustrates giving a tip: @@ -527,7 +530,7 @@ Product Identification In some situations the user may have paid for some digital good, but the frontend does not know the exact order ID, and thus cannot instruct the -wallet to reveil the existing payment receipt. This is common for simple +wallet to reveal the existing payment receipt. This is common for simple shops without a login system. In this case, the user would be prompted for payment again, even though they already purchased the product. @@ -564,7 +567,7 @@ max_fee This is the maximum total amount of deposit fees that the merchant is willing to pay. If the deposit fees for the coins exceed this amount, the customer has to include it in the payment total. The fee is - specified using the same triplet used for ``amount``. + specified using the same format used for ``amount``. .. index:: fees .. index:: maximum wire fee @@ -652,7 +655,7 @@ products or just the count. price - Price for quantity units of this product shipped to the given + Price for ``quantity`` units of this product shipped to the given ``delivery_location``. Note that usually the sum of all of the prices should add up to the total amount of the contract, but it may be different due to discounts or because individual prices are @@ -675,17 +678,17 @@ products delivery_date Time by which the product is to be delivered to the - delivery_location. + ``delivery_location``. delivery_location - This should give a label in the locations map, specifying where + This should give a label in the ``locations`` map, specifying where the item is to be delivered. Values can be omitted if they are not applicable. For example, if a purchase is about a bundle of products that have no individual prices - or product IDs, the product_id or price may not be specified in the + or product IDs, the ``product_id`` or ``price`` may not be specified in the contract. Similarly, for virtual products delivered directly via the - fulfillment URI, there is no delivery location. + fulfillment URI, there is no ``delivery_location``. merchant address |