fix #7923

1 files changed, 97 insertions, 99 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 56c6e3c5..ea059ac7 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -2578,36 +2578,34 @@ once we got a reply from the exchange.
     The transfer cannot be deleted anymore.
 
 
---------------------
-Backend: Giving tips
---------------------
+-----------------------
+Backend: Giving rewards
+-----------------------
 
-Tips are a way for websites to give small amounts of e-cash to visitors (for
+Rewards are a way for websites to give small amounts of e-cash to visitors (for
 example as a financial reward for providing information or watching
-advertizements).  Tips are non-contractual: neither merchant nor consumer
+advertizements).  Rewards are non-contractual: neither merchant nor consumer
 have any contractual information about the other party as a result of the
-tip.
+reward.
 
 
 Create reserve
 --------------
 
-Reserves are basically funds a merchant has provided
-to an exchange for a tipping campaign. Each reserve
-has a limited lifetime (say 2--4 weeks). Any funds
-not used to tip customers will automatically be wired
-back from the exchange to the originating account.
+Reserves are basically funds a merchant has provided to an exchange for a
+rewards campaign. Each reserve has a limited lifetime (say 2--4 weeks). Any
+funds not used to reward customers will automatically be wired back from the
+exchange to the originating account.
 
-To begin tipping, a merchant must tell the backend
-to set up a reserve. The backend will return a
-reserve public key which must be used as the wire
-transfer subject when wiring the tipping campaign
-funds to the exchange.
+Before handing out rewards, a merchant must tell the backend to set up a
+reserve. The backend will return a reserve public key which must be used as
+the wire transfer subject when wiring the reward campaign funds to the
+exchange.
 
-.. _tips:
+.. _rewards:
 .. http:post:: [/instances/$INSTANCE]/private/reserves
 
-  Create a reserve for tipping.
+  Create a reserve for rewards.
 
   This request is **not** idempotent.  However, while repeating
   it will create another reserve, that is generally pretty harmless
@@ -2627,7 +2625,7 @@ funds to the exchange.
   :http:statuscode:`408 Request timeout`:
     The exchange did not respond on time.
   :http:statuscode:`409 Conflict`:
-    The exchange does not support the requested wire method or does not allow tipping.
+    The exchange does not support the requested wire method or does not allow rewards.
   :http:statuscode:`502 Bad gateway`:
     We could not obtain ``/wire`` details from the specified exchange base URL.
   :http:statuscode:`504 Gateway timeout`:
@@ -2640,7 +2638,7 @@ funds to the exchange.
       // Amount that the merchant promises to put into the reserve.
       initial_balance: Amount;
 
-      // Exchange the merchant intends to use for tipping.
+      // Exchange the merchant intends to use for rewards.
       exchange_url: string;
 
       // Desired wire method, for example "iban" or "x-taler-bank".
@@ -2659,7 +2657,7 @@ funds to the exchange.
 
 .. http:get:: [/instances/$INSTANCE]/private/reserves
 
-  Obtain list of reserves that have been created for tipping.
+  Obtain list of reserves that have been created for rewards.
 
   **Request:**
 
@@ -2670,12 +2668,12 @@ funds to the exchange.
   **Response:**
 
   :http:statuscode:`200 OK`:
-    Returns a list of known tipping reserves.
-    The body is a `TippingReserveStatus`.
+    Returns a list of known reward reserves.
+    The body is a `RewardReserveStatus`.
 
-  .. ts:def:: TippingReserveStatus
+  .. ts:def:: RewardReserveStatus
 
-    interface TippingReserveStatus {
+    interface RewardReserveStatus {
       // Array of all known reserves (possibly empty!).
       reserves: ReserveStatusEntry[];
     }
@@ -2702,7 +2700,7 @@ funds to the exchange.
       // Amount picked up so far.
       pickup_amount: Amount;
 
-      // Amount approved for tips that exceeds the pickup_amount.
+      // Amount approved for rewards that exceeds the pickup_amount.
       committed_amount: Amount;
 
       // Is this reserve active (false if it was deleted but not purged)?
@@ -2715,18 +2713,18 @@ Query funds remaining
 
 .. http:get:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB
 
-  Obtain information about a specific reserve that have been created for tipping.
+  Obtain information about a specific reserve that have been created for rewards.
 
   **Request:**
 
-  :query tips: *Optional*. If set to "yes", returns also information about all of the tips created.
+  :query rewards: *Optional*. If set to "yes", returns also information about all of the rewards created.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Returns the `ReserveDetail`.
   :http:statuscode:`404 Not found`:
-    The tipping reserve is not known.
+    The reward reserve is not known.
   :http:statuscode:`502 Bad gateway`:
     We are having trouble with the request because of a problem with the exchange.
     Likely returned with an "exchange_code" in addition to a "code" and
@@ -2758,12 +2756,12 @@ Query funds remaining
       // Amount picked up so far.
       pickup_amount: Amount;
 
-      // Amount approved for tips that exceeds the pickup_amount.
+      // Amount approved for rewards that exceeds the pickup_amount.
       committed_amount: Amount;
 
-      // Array of all tips created by this reserves (possibly empty!).
+      // Array of all rewards created by this reserves (possibly empty!).
       // Only present if asked for explicitly.
-      tips?: TipStatusEntry[];
+      rewards?: RewardStatusEntry[];
 
       // Is this reserve active (false if it was deleted but not purged)?
       active: boolean;
@@ -2778,92 +2776,92 @@ Query funds remaining
       exchange_url: string;
     }
 
-  .. ts:def:: TipStatusEntry
+  .. ts:def:: RewardStatusEntry
 
-    interface TipStatusEntry {
+    interface RewardStatusEntry {
 
-      // Unique identifier for the tip.
-      tip_id: HashCode;
+      // Unique identifier for the reward.
+      reward_id: HashCode;
 
-      // Total amount of the tip that can be withdrawn.
+      // Total amount of the reward that can be withdrawn.
       total_amount: Amount;
 
-      // Human-readable reason for why the tip was granted.
+      // Human-readable reason for why the reward was granted.
       reason: string;
     }
 
 
-Authorizing tips
-----------------
+Authorizing rewards
+-------------------
 
-.. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-tip
+.. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-reward
 
-  Authorize creation of a tip from the given reserve.
+  Authorize creation of a reward from the given reserve.
 
   **Request:**
 
-  The request body is a `TipCreateRequest` object.
+  The request body is a `RewardCreateRequest` object.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    A tip has been created. The backend responds with a `TipCreateConfirmation`.
+    A reward has been created. The backend responds with a `RewardCreateConfirmation`.
   :http:statuscode:`404 Not found`:
     The instance or the reserve is unknown to the backend.
   :http:statuscode:`412 Precondition failed`:
-    The tip amount requested exceeds the available reserve balance for tipping.
+    The reward amount requested exceeds the available reserve balance for rewards.
 
-  .. ts:def:: TipCreateRequest
+  .. ts:def:: RewardCreateRequest
 
-    interface TipCreateRequest {
-      // Amount that the customer should be tipped.
+    interface RewardCreateRequest {
+      // Amount that the customer should be rewarded.
       amount: Amount;
 
-      // Justification for giving the tip.
+      // Justification for giving the reward.
       justification: string;
 
-      // URL that the user should be directed to after tipping,
-      // will be included in the tip_token.
+      // URL that the user should be directed to after receiving the reward,
+      // will be included in the reward_token.
       next_url: string;
     }
 
-  .. ts:def:: TipCreateConfirmation
+  .. ts:def:: RewardCreateConfirmation
 
-    interface TipCreateConfirmation {
-      // Unique tip identifier for the tip that was created.
-      tip_id: HashCode;
+    interface RewardCreateConfirmation {
+      // Unique reward identifier for the reward that was created.
+      reward_id: HashCode;
 
-      // taler://tip URI for the tip.
-      taler_tip_uri: string;
+      // taler://reward URI for the reward.
+      taler_reward_uri: string;
 
       // URL that will directly trigger processing
-      // the tip when the browser is redirected to it.
-      tip_status_url: string;
+      // the reward when the browser is redirected to it.
+      reward_status_url: string;
 
-      // When does the tip expire?
-      tip_expiration: Timestamp;
+      // When does the reward expire?
+      reward_expiration: Timestamp;
     }
 
 
-.. http:post:: [/instances/$INSTANCE]/private/tips
+.. http:post:: [/instances/$INSTANCE]/private/rewards
 
-  Authorize creation of a tip, with
+  Authorize creation of a reward, with
   automatic selection of a working reserve of the instance by the
-  backend. Intentionally otherwise identical to the ``/authorize-tip``
+  backend. Intentionally otherwise identical to the ``/authorize-reward``
   endpoint given above.
 
   **Request:**
 
-  The request body is a `TipCreateRequest` object.
+  The request body is a `RewardCreateRequest` object.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    A tip has been created. The backend responds with a `TipCreateConfirmation`.
+    A reward has been created. The backend responds with a `RewardCreateConfirmation`.
   :http:statuscode:`404 Not found`:
     The instance is unknown to the backend.
   :http:statuscode:`412 Precondition failed`:
-    The tip amount requested exceeds the available reserve balance for tipping
+    The reward amount requested exceeds the available reserve balance for rewards
     in all of the reserves of the instance.
 
 
@@ -2873,13 +2871,13 @@ Deleting reserves
 .. http:delete:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB
 
   Delete information about a reserve.  Fails if the reserve still has
-  committed to tips that were not yet picked up and that have not yet
+  committed to rewards that were not yet picked up and that have not yet
   expired.
 
   **Request:**
 
   :query purge: *Optional*. If set to YES, the reserve and all information
-      about tips it issued will be fully deleted.
+      about rewards it issued will be fully deleted.
       Otherwise only the private key would be deleted.
 
   **Response:**
@@ -2889,48 +2887,48 @@ Deleting reserves
   :http:statuscode:`404 Not found`:
     The backend does not know the instance or the reserve.
   :http:statuscode:`409 Conflict`:
-    The backend refuses to delete the reserve (committed tips awaiting pickup).
+    The backend refuses to delete the reserve (committed rewards awaiting pickup).
 
 
-Checking tip status
--------------------
+Checking reward status
+----------------------
 
-.. http:get:: [/instances/$INSTANCE]/private/tips/$TIP_ID
+.. http:get:: [/instances/$INSTANCE]/private/rewards/$REWARD_ID
 
-  Obtain information about a particular tip.
+  Obtain information about a particular reward.
 
   **Request:**
 
   :query pickups: *Optional*. If set to "yes", returns also information about all of the pickups.
   :query min_amount: *Optional*. Minimum pick-up amount the client is interested in.
   :query timeout_ms=NUMBER: *Optional.*  If specified, the merchant backend will
-    wait up to ``timeout_ms`` milliseconds for tips of at least min_pick_up to be
+    wait up to ``timeout_ms`` milliseconds for rewards of at least min_pick_up to be
     picked up.  A client must never rely on this behavior, as the
     merchant backend may return a response immediately.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The tip is known. The backend responds with a `TipDetails` message.
+    The reward is known. The backend responds with a `RewardDetails` message.
   :http:statuscode:`404 Not found`:
-    The tip is unknown to the backend.
+    The reward is unknown to the backend.
 
-  .. ts:def:: TipDetails
+  .. ts:def:: RewardDetails
 
-    interface TipDetails {
-      // Amount that we authorized for this tip.
+    interface RewardDetails {
+      // Amount that we authorized for this reward.
       total_authorized: Amount;
 
       // Amount that was picked up by the user already.
       total_picked_up: Amount;
 
-      // Human-readable reason given when authorizing the tip.
+      // Human-readable reason given when authorizing the reward.
       reason: string;
 
-      // Timestamp indicating when the tip is set to expire (may be in the past).
+      // Timestamp indicating when the reward is set to expire (may be in the past).
       expiration: Timestamp;
 
-      // Reserve public key from which the tip is funded.
+      // Reserve public key from which the reward is funded.
       reserve_pub: EddsaPublicKey;
 
       // Array showing the pickup operations of the wallet (possibly empty!).
@@ -2952,13 +2950,13 @@ Checking tip status
     }
 
 
-.. http:get:: [/instances/$INSTANCE]/private/tips
+.. http:get:: [/instances/$INSTANCE]/private/rewards
 
-  Return the list of all tips.
+  Return the list of all rewards.
 
   **Request:**
 
-  :query include_expired: *Optional*. If set to "yes", the result includes expired tips also. Otherwise, only active tips are returned.
+  :query include_expired: *Optional*. If set to "yes", the result includes expired rewards also. Otherwise, only active rewards are returned.
 
   :query limit: *Optional*. At most return the given number of results. Negative for descending in database row id, positive for ascending in database row id.
 
@@ -2967,29 +2965,29 @@ Checking tip status
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The backend has successfully found the list of tips. The backend responds
-    with a `TipsResponse`.
+    The backend has successfully found the list of rewards. The backend responds
+    with a `RewardsResponse`.
 
-  .. ts:def:: TipsResponse
+  .. ts:def:: RewardsResponse
 
-    interface TipsResponse {
+    interface RewardsResponse {
 
-      // List of tips that are present in the backend.
-      tips: Tip[];
+      // List of rewards that are present in the backend.
+      rewards: Reward[];
     }
 
-  .. ts:def:: Tip
+  .. ts:def:: Reward
 
-     interface Tip {
+     interface Reward {
 
-      // ID of the tip in the backend database.
+      // ID of the reward in the backend database.
       row_id: number;
 
-      // Unique identifier for the tip.
-      tip_id: HashCode;
+      // Unique identifier for the reward.
+      reward_id: HashCode;
 
-      // (Remaining) amount of the tip (including fees).
-      tip_amount: Amount;
+      // (Remaining) amount of the reward (including fees).
+      reward_amount: Amount;
     }
 
 -----------