regen

1 files changed, 83 insertions, 11 deletions

diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi
index fdc0b16a..33970265 100644
--- a/texinfo/taler-merchant-api-tutorial.texi
+++ b/texinfo/taler-merchant-api-tutorial.texi
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-GNU Taler 0.9.0, Feb 10, 2024
+GNU Taler 0.9.0, Jan 06, 2024
 
 GNU Taler team
 
@@ -69,6 +69,7 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
 * Merchant Payment Processing:: 
 * Giving Refunds:: 
 * Repurchase detection and fulfillment URLs:: 
+* Giving Customers Rewards:: 
 * Advanced topics:: 
 * Index:: 
 
@@ -157,6 +158,11 @@ that accepts donations for software projects and gives donation
 receipts.
 
 @item 
+The
+survey@footnote{https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/survey}
+that gives users who answer a question a small reward.
+
+@item 
 The WooCommerce plugin@footnote{https://git.taler.net/gnu-taler-payment-for-woocommerce.git/}
 which is a comprehensive integration into a Web shop including the refund business
 process.
@@ -449,7 +455,7 @@ the merchant’s obligations under the contract.
 @cartouche
 @quotation Note 
 You do not need to keep querying to notice changes
-to the order's transaction status.  The endpoints
+to the order’s transaction status.  The endpoints
 support long polling, simply specify a @code{timeout_ms}
 query parameter with how long you want to wait at most
 for the order status to change to @code{paid}.
@@ -525,7 +531,7 @@ under the @code{h_contract} field.
 
 @geindex repurchase
 
-@node Repurchase detection and fulfillment URLs,Advanced topics,Giving Refunds,Top
+@node Repurchase detection and fulfillment URLs,Giving Customers Rewards,Giving Refunds,Top
 @anchor{taler-merchant-api-tutorial repurchase}@anchor{10}@anchor{taler-merchant-api-tutorial repurchase-detection-and-fulfillment-urls}@anchor{11}
 @chapter Repurchase detection and fulfillment URLs
 
@@ -547,8 +553,8 @@ from the QR code).
 
 The merchant backend then updates the session ID of the existing order to
 the current session ID of the browser.  When the payment status for the
-"new" unpaid order is checked (or already in long-polling), the backend
-detects that for the browser's `session ID' and `fulfillment URL' there is an
+“new” unpaid order is checked (or already in long-polling), the backend
+detects that for the browser’s `session ID' and `fulfillment URL' there is an
 existing paid contract. It then tells the browser to immediately redirect to
 the fulfillment URL where the already paid article is available.
 
@@ -565,9 +571,75 @@ also `only' done for HTTP(S) fulfillment URLs. In particular, this means
 fulfillment URIs like @code{taler://fulfillment-success/$MESSAGE} are not
 considered to identify a resource you can pay for and thus do not have to be
 unique.
+@anchor{taler-merchant-api-tutorial giving-customers-rewards}@anchor{12}
+@geindex rewards
+
+@node Giving Customers Rewards,Advanced topics,Repurchase detection and fulfillment URLs,Top
+@anchor{taler-merchant-api-tutorial id3}@anchor{13}
+@chapter 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 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
+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 rewards, and
+sufficient funds must be made available for rewards. See the Taler User
+Guide for details.
+
+To check if rewards are configured properly and if there are sufficient
+funds available for granting rewards, query the @code{/private/reserves} endpoint:
+
+@example
+>>> import requests
+>>> requests.get("https://backend.demo.taler.net/private/reserves",
+...              headers=@{"Authorization": "Bearer secret-token:sandbox"@})
+<Response [200]>
+@end example
+
+Check that a reserve exists where the @code{merchant_initial_amount} is below the
+@code{committed_amount} and that the reserve is @code{active}.
+@anchor{taler-merchant-api-tutorial authorize-reward}@anchor{14}
+To authorize a reward, @code{POST} to @code{/private/rewards}. The following fields
+are recognized in the JSON request object:
+
+
+@itemize -
 
-@node Advanced topics,Index,Repurchase detection and fulfillment URLs,Top
-@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{12}@anchor{taler-merchant-api-tutorial id3}@anchor{13}
+@item 
+@code{amount}: Amount that should be given to the visitor as a reward.
+
+@item 
+@code{justification}: Description of why the reward was granted. Human-readable
+text not exposed to the customer, but used by the Back Office.
+
+@item 
+@code{next_url}: The URL that the user’s browser should be redirected to by
+the wallet, once the reward has been processed.
+@end itemize
+
+The response from the backend contains a @code{taler_reward_url}. The
+customer’s browser must be redirected to this URL for the wallet to pick
+up the reward.
+@anchor{taler-merchant-api-tutorial pick-up-reward}@anchor{15}
+This code snipped illustrates giving a reward:
+
+@example
+>>> import requests
+>>> 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/rewards", json=reward_req,
+...              headers=@{"Authorization": "Bearer secret-token:sandbox"@})
+<Response [200]>
+@end example
+
+@node Advanced topics,Index,Giving Customers Rewards,Top
+@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{16}@anchor{taler-merchant-api-tutorial id4}@anchor{17}
 @chapter Advanced topics
 
 
@@ -579,7 +651,7 @@ unique.
 @end menu
 
 @node Session-Bound Payments,Product Identification,,Advanced topics
-@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{14}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{15}
+@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{18}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{19}
 @section Session-Bound Payments
 
 
@@ -616,7 +688,7 @@ receipt is in the user’s wallet is also available as @code{last_session_id}
 in the response to @code{/check-payment}.
 
 @node Product Identification,The Taler Order Format,Session-Bound Payments,Advanced topics
-@anchor{taler-merchant-api-tutorial id4}@anchor{16}@anchor{taler-merchant-api-tutorial product-identification}@anchor{17}
+@anchor{taler-merchant-api-tutorial id5}@anchor{1a}@anchor{taler-merchant-api-tutorial product-identification}@anchor{1b}
 @section Product Identification
 
 
@@ -637,7 +709,7 @@ contract with the same @code{resource_url} before, and if so replay the
 previous payment.
 
 @node The Taler Order Format,,Product Identification,Advanced topics
-@anchor{taler-merchant-api-tutorial id5}@anchor{18}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{19}
+@anchor{taler-merchant-api-tutorial id6}@anchor{1c}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1d}
 @section The Taler Order Format
 
 
@@ -948,8 +1020,8 @@ render fields that they do not understand as a key-value list.
 
 @printindex ge
 
-@anchor{c}@w{                              }
 @anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{                              }
+@anchor{c}@w{                              }
 
 @c %**end of body
 @bye