fix #7455

2 files changed, 28 insertions, 33 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 53a0f65e..47e6148c 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -2867,7 +2867,7 @@ Authorizing tips
 
 .. http:post:: [/instances/$INSTANCE]/private/tips
 
-  Authorize creation of a tip from the given reserve, except with
+  Authorize creation of a tip, with
   automatic selection of a working reserve of the instance by the
   backend. Intentionally otherwise identical to the ``/authorize-tip``
   endpoint given above.
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index d45ed4fa..25fc890d 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014-2020 Taler Systems SA
+  Copyright (C) 2014-2023 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -125,13 +125,13 @@ configuration. See :doc:`taler-merchant-manual`.
 
 The public sandbox backend https://backend.demo.taler.net/ uses an API
 key in the ``Authorization`` header. The value of this header must be
-``ApiKey sandbox`` for the public sandbox backend.
+``Bearer secret-token:sandbox`` for the public sandbox backend.
 
 .. code-block:: python
 
    >>> import requests
-   >>> requests.get("https://backend.demo.taler.net",
-   ...              headers={"Authorization": "secret-token:secret"})
+   >>> requests.get("https://backend.demo.taler.net/private/orders",
+   ...              headers={"Authorization": "Bearer secret-token:secret"})
    <Response [200]>
 
 If an HTTP status code other than 200 is returned, something went wrong.
@@ -147,9 +147,9 @@ https://bank.demo.taler.net/.
 Merchant Instances
 ------------------
 
-The same Taler merchant backend server can be used by multiple separate
+A single Taler merchant backend server can be used by multiple
 merchants that are separate business entities. Each of these separate
-business entities is called a *merchant instance*, and is identified by
+business entities is assigned a *merchant instance* which is identified by
 an alphanumeric *instance id*. If the instance is omitted, the instance
 id ``default`` is assumed.
 
@@ -372,8 +372,6 @@ This code snipped illustrates giving a refund:
 Repurchase detection and fulfillment URLs
 =========================================
 
-.. TODO:: This section needs to be reviewed for 0.8.
-
 A possible problem for merchants selling access to digital articles
 is that a customer may have paid for an article on one device, but
 may then want to read it on a different device, possibly one that
@@ -417,48 +415,45 @@ unique.
 Giving Customers Tips
 =====================
 
-.. TODO:: This section needs to be updated for 0.8.
-
-
-GNU Taler allows Web sites to grant small amounts directly to the
-visitor. The idea is that some sites may want incentivize actions such
-as filling out a survey or trying a new feature. It is important to note
-that tips are not enforceable for the visitor, as there is no contract.
-It is simply a voluntary gesture of appreciation of the site to its
-visitor. However, once a tip has been granted, the visitor obtains full
-control over the funds provided by the site.
+GNU Taler allows Web sites to grant digital cash directly to a visitor. The
+idea is that some sites may want incentivize actions such as filling out a
+survey or trying a new feature. It is important to note that receiving tips is
+not enforceable for the visitor, as there is no contract.  It is simply a
+voluntary gesture of appreciation of the site to its visitor. However, once a
+tip has been granted, the visitor obtains full control over the funds provided
+by the site.
 
-The “merchant” backend of the site must be properly configured for
-tipping, and sufficient funds must be made available for tipping See
-Taler Merchant Operating Manual.
+The merchant backend of the site must be properly configured for tipping, and
+sufficient funds must be made available for tipping. See the :ref:`Taler
+Merchant Operating Manual <Tipping-visitors>` for details.
 
 To check if tipping is configured properly and if there are sufficient
-funds available for tipping, query the ``/tip-query`` endpoint:
+funds available for tipping, query the ``/private/reserves`` endpoint:
 
 .. code-block:: python
 
    >>> import requests
-   >>> requests.get("https://backend.demo.taler.net/tip-query?instance=default",
-   ...              headers={"Authorization": "secret-token:secret"})
+   >>> requests.get("https://backend.demo.taler.net/private/reserves",
+   ...              headers={"Authorization": "Bearer secret-token:secret"})
    <Response [200]>
 
+Check that a reserve exists where the ``merchant_initial_amount`` is below the
+``committed_amount`` and that the reserve is ``active``.
+
 .. _authorize-tip:
 
-To authorize a tip, ``POST`` to ``/tip-authorize``. The following fields
+To authorize a tip, ``POST`` to ``/private/tips``. The following fields
 are recognized in the JSON request object:
 
 -  ``amount``: Amount that should be given to the visitor as a tip.
 
--  ``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
    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
    the wallet, once the tip has been processed.
 
-The response from the backend contains a ``tip_redirect_url``. The
+The response from the backend contains a ``taler_tip_url``. The
 customer’s browser must be redirected to this URL for the wallet to pick
 up the tip.
 
@@ -470,13 +465,13 @@ This code snipped illustrates giving a tip:
 
    >>> import requests
    >>> tip_req = dict(amount="KUDOS:0.5",
-   ...                instance="default",
    ...                justification="User filled out survey",
    ...                next_url="https://merchant.com/thanks.html")
-   >>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req,
-   ...              headers={"Authorization": "secret-token:secret"})
+   >>> requests.post("https://backend.demo.taler.net/private/tips", json=tip_req,
+   ...              headers={"Authorization": "Bearer secret-token:secret"})
    <Response [200]>
 
+
 .. _Advanced-topics:
 
 Advanced topics