commit 50c89041aa9b5f7300ddaa7b2b1412617101eeac
parent a1eb5922a9985c910d1a7e4c136c82a8ea394d83
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 16 Jul 2023 17:07:51 +0200
tip -> reward
Diffstat:
8 files changed, 68 insertions(+), 73 deletions(-)
diff --git a/checklist-demo-upgrade.rst b/checklist-demo-upgrade.rst
@@ -78,16 +78,16 @@ Merchant SPA:
- |check| pay for order with wallet
- |check| trigger refund
- |check| accept refund with wallet
-- |check| TBD: tipping
+- |check| TBD: rewards
- |check| TBD: products with previews
- |check| TBD: inventory management
- |check| TBD: adding transactions
- |check| TBD: test various settings
- |check| TBD: ...
-Survey/Tipping:
+Survey/Rewards:
-- |check| Visit https://survey.demo.taler.net/ and receive a tip.
+- |check| Visit https://survey.demo.taler.net/ and receive a reward.
- |check| Verify that the survey stats page (https://survey.demo.taler.net/survey-stats) is working,
and that the survey reserve has sufficient funds.
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst
@@ -97,7 +97,7 @@ overview:
* taler-merchant-demos: various demonstration services operated at
'demo.taler.net', including a simple shop, donation page and a
- survey with tipping functionality.
+ survey with reward functionality.
There are other important repositories without code, including:
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -1353,7 +1353,7 @@ Taler permits an exchange to require KYC data under the following circumstances:
* Wallet receives (via refunds) money resulting in a balance over a threshold
* Wallet receives money via P2P payments over a threshold
* Merchant receives money over a threshold
- * Reserve is "opened" for invoicing or tipping (**planned feature**)
+ * Reserve is "opened" for invoicing or rewards (**planned feature**)
Taler KYC Terminology
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
@@ -409,26 +409,26 @@ considered to identify a resource you can pay for and thus do not have to be
unique.
-.. _Giving-Customers-Tips:
-.. index:: tips
+.. _Giving-Customers-Rewards:
+.. index:: rewards
-Giving Customers Tips
-=====================
+Giving Customers Rewards
+========================
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
+survey or trying a new feature. It is important to note that receiving rewards 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
+reward 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 the :ref:`Taler
-Merchant Operating Manual <Tipping-visitors>` for details.
+The merchant backend of the site must be properly configured for rewards, and
+sufficient funds must be made available for rewards. See the :ref:`Taler User
+Guide <Rewarding-visitors>` for details.
-To check if tipping is configured properly and if there are sufficient
-funds available for tipping, query the ``/private/reserves`` endpoint:
+To check if rewards are configured properly and if there are sufficient
+funds available for granting rewards, query the ``/private/reserves`` endpoint:
.. code-block:: python
@@ -440,34 +440,34 @@ funds available for tipping, query the ``/private/reserves`` endpoint:
Check that a reserve exists where the ``merchant_initial_amount`` is below the
``committed_amount`` and that the reserve is ``active``.
-.. _authorize-tip:
+.. _authorize-reward:
-To authorize a tip, ``POST`` to ``/private/tips``. The following fields
+To authorize a reward, ``POST`` to ``/private/rewards``. 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 reward.
-- ``justification``: Description of why the tip was granted. Human-readable
+- ``justification``: Description of why the reward 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 wallet, once the reward has been processed.
-The response from the backend contains a ``taler_tip_url``. The
+The response from the backend contains a ``taler_reward_url``. The
customer’s browser must be redirected to this URL for the wallet to pick
-up the tip.
+up the reward.
-.. _pick-up-tip:
+.. _pick-up-reward:
-This code snipped illustrates giving a tip:
+This code snipped illustrates giving a reward:
.. code-block:: python
>>> import requests
- >>> tip_req = dict(amount="KUDOS:0.5",
+ >>> reward_req = dict(amount="KUDOS:0.5",
... justification="User filled out survey",
... next_url="https://merchant.com/thanks.html")
- >>> requests.post("https://backend.demo.taler.net/private/tips", json=tip_req,
+ >>> requests.post("https://backend.demo.taler.net/private/rewards", json=reward_req,
... headers={"Authorization": "Bearer secret-token:secret"})
<Response [200]>
@@ -477,8 +477,6 @@ This code snipped illustrates giving a tip:
Advanced topics
===============
-.. TODO:: This section needs to be updated for 0.8.
-
.. _Session_002dBound-Payments:
Session-Bound Payments
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -276,26 +276,25 @@ backend with wire *transfer* data that specifies the *wire transfer subject*
and the amount that was received. Given this information, the backend can
detect and report any irregularities that might arise.
-Tipping
+Rewards
-------
-.. index:: tip
-.. index:: grant
+.. index:: reward
.. index:: pick up
Taler does not only allow a Website to be paid, but also to make voluntary,
-non-contractual payments to visitors, called *tips*. Such tips could be
+non-contractual payments to visitors, called *rewards*. Such rewards could be
granted as a reward for filling in surveys or watching advertizements. For
-tips, there is no contract, tips are always voluntary actions by the Web
+rewards, there is no contract, rewards are always voluntary actions by the Web
site that do not arise from a contractual obligation. Before a Web site
-can create tips, it must establish a reserve. Once a reserve has been
-established, the merchant can *grant* tips, allowing wallets to *pick up*
-the tip.
+can create rewards, it must establish a reserve. Once a reserve has been
+established, the merchant can *grant* rewards, allowing wallets to *pick up*
+the reward.
..note::
- Tipping is an optional feature, and exchanges may disable tipping (usually
- if they see compliance issues). In this case, the tipping feature will
+ Rewards are an optional feature, and exchanges may disable rewards (usually
+ if they see compliance issues). In this case, the reward feature will
not be available.
@@ -307,7 +306,7 @@ Reserves
A *reserve* is a pool of electronic cash at an exchange under the control of
a private key. Merchants withdraw coins from a reserve when granting
-tips. A reserve is established by first generating the required key material
+rewards. A reserve is established by first generating the required key material
in the merchant backend, and then wiring the desired amount of funds to the
exchange.
diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst
@@ -232,7 +232,7 @@ to dereference the ``taler://pay`` URI from the example above:
m<-w 9000
(Note that this process works analogously for communication between a bank/ATM
-terminal or "tipping provider".)
+terminal or "reward provider".)
Request tunneling
diff --git a/taler-user-guide.rst b/taler-user-guide.rst
@@ -325,20 +325,20 @@ Mustach templating engine:
-.. _Tipping-visitors:
+.. _Rewarding-visitors:
-Tipping visitors
-================
+Rewarding visitors
+==================
-.. index:: tipping
+.. index:: rewards
-Taler can also be used to tip Web site visitors. For example, you may be
-running an online survey, and you want to reward those people that have
-dutifully completed the survey. If they have installed a Taler wallet,
-you can provide them with a tip for their deeds. This section describes
-how to setup the Taler merchant backend for tipping.
+Taler can also be used to reward digital cash to Web site visitors. For
+example, you may be running an online survey, and you want to reward those
+people that have dutifully completed the survey. If they have installed a
+Taler wallet, you can provide them with a reward for their deeds. This section
+describes how to setup the Taler merchant backend for rewarding.
-There are three basic steps that must happen to tip a visitor.
+There are three basic steps that must happen to reward a visitor.
.. _Fund-the-reserve:
@@ -384,7 +384,7 @@ Make your wire transfer and (optionally) check at
exchange.
Once the funds have arrived, you can start to use the reserve for
-tipping.
+rewarding.
Note that an exchange will typically close a reserve after four weeks, wiring
all remaining funds back to the sender’s account. Thus, you should plan to
@@ -392,45 +392,43 @@ wire funds corresponding to a campaign of about two weeks to the exchange
initially. If your campaign runs longer, you should setup another reserve
every other week to ensure one is always ready.
-.. _Authorize-a-tip:
+.. _Authorize-a-reward:
-Authorize a tip
----------------
+Authorize a reward
+------------------
When your frontend has reached the point where a client is supposed to receive
-a tip, it needs to first authorize the tip. For this, the frontend must use
-a POST to ``/private/reserves/$RESERVE_PUB/authorize-tip``. To authorize a
-tip, the frontend has to provide the following information in the body of the
+a reward, it needs to first authorize the reward. For this, the frontend must use
+a POST to ``/private/reserves/$RESERVE_PUB/authorize-reward``. To authorize a
+reward, the frontend has to provide the following information in the body of the
POST request:
-- The amount of the tip
+- The amount of the reward
- The justification (only used internally for the back-office)
-- The URL where the wallet should navigate next after the tip was
+- The URL where the wallet should navigate next after the reward was
processed
-- The tip-pickup URL (see next section)
+- The reward-pickup URL (see next section)
-In response to this request, the backend will return a tip token, an
+In response to this request, the backend will return a reward token, an
expiration time and the exchange URL. The expiration time will indicate
-how long the tip is valid (when the reserve expires). The tip token is
+how long the reward is valid (when the reserve expires). The reward token is
an opaque string that contains all the information needed by the wallet
-to process the tip. The frontend must send this tip token to the browser
-in a special “402 Payment Required” response inside the ``X-Taler-Tip``
+to process the reward. The frontend must send this reward token to the browser
+in a special “402 Payment Required” response inside the ``Taler``
header.
The frontend should handle errors returned by the backend, such as
-misconfigured instances or a lack of remaining funds for tipping.
+misconfigured instances or a lack of remaining funds for rewarding.
-.. _Picking-up-of-the-tip:
+.. _Picking-up-of-the-reward:
-Picking up of the tip
----------------------
+Picking up of the reward
+------------------------
The wallet will POST a JSON object to the shop’s
-``/tips/$TIP_ID/pickup`` handler.
+``/rewards/$REWARD_ID/pickup`` handler.
The frontend must then forward this request to the backend. The response
generated by the backend can then be forwarded directly to the wallet.
-
-
diff --git a/taler-wallet.rst b/taler-wallet.rst
@@ -389,7 +389,7 @@ Things we still need tests for:
Or when the merchant is not reachable? Or the bank?
This can be tested by temporarily killing those services.
* How does the wallet deal with processing the same ``taler://(pay|withdraw)`` URI twice?
-* Test tipping (accepting/refusing a tip)
+* Test rewards (accepting/refusing a reward)
* Test refunds
* Test for :ref:`session-based payments <repurchase>`
* Test case for auto-refunds
