diff options
Diffstat (limited to 'taler-merchant-api-tutorial.rst')
| -rw-r--r-- | taler-merchant-api-tutorial.rst | 88 |
1 files changed, 76 insertions, 12 deletions
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index ea8f72b6..eb9505ce 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -1,5 +1,26 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2020 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Marcello Stanisci + @author Florian Dold + @author Christian Grothoff + +.. _merchant-api-tutorial: + GNU Taler Merchant API Tutorial -################################### +############################### Introduction ============ @@ -66,7 +87,7 @@ components: The following image illustrates the various interactions of these key components: -|image0| +.. image:: arch-api.png The backend provides the cryptographic protocol support, stores Taler-specific financial information and communicates with the GNU Taler @@ -80,11 +101,12 @@ Some functionality of the backend (the “public interface“) is also exposed to the customer’s browser directly. In the HTTP API, all public endpoints are prefixed with ``/public/``. + +.. index:: sandbox, authorization + Public Sandbox Backend and Authentication ----------------------------------------- -sandbox -authorization How the frontend authenticates to the Taler backend depends on the configuration. See Taler Merchant Operating Manual. @@ -107,10 +129,11 @@ The sandbox backend https://backend.demo.taler.net/ uses ``KUDOS`` as an imaginary currency. Coins denominated in ``KUDOS`` can be withdrawn from https://bank.demo.taler.net/. +.. index:: instance + Merchant Instances ------------------ -instance The same Taler merchant backend server can be used by multiple separate merchants that are separate business entities. Each of these separate business entities is called a *merchant instance*, and is identified by @@ -136,10 +159,11 @@ not affiliated with or officially approved by the respective projects. Accepting a Simple Payment ========================== +.. index:: order + Creating an Order for a Payment ------------------------------- -order Payments in Taler revolve around an *order*, which is a machine-readable description of the business transaction for which the payment is to be made. Before accepting a Taler payment as a merchant you must create @@ -225,11 +249,11 @@ usually needs to trigger the business logic for the merchant to fulfill the merchant’s obligations under the contract. .. _Giving-Refunds: +.. index:: refunds Giving Refunds ============== -refunds A refund in GNU Taler is a way to “undo” a payment. It needs to be authorized by the merchant. Refunds can be for any fraction of the original amount paid, but they cannot exceed the original payment. @@ -274,12 +298,56 @@ This code snipped illustrates giving a refund: ... headers={"Authorization": "ApiKey sandbox"}) <Response [200]> + +.. index:: repurchase +.. _repurchase: + +Repurchase detection and fulfillment URLs +========================================= + +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 +does not even have a Taler wallet installed. + +Naturally, at this point the customer would at first still be prompted to pay +for the article again. If the customer then opens the taler://-link in the +wallet that did previously pay for the article (for example by scanning the QR +code on the desktop with the Android App), the wallet will claim the contract, +detect that the fulfillment URL is identical to one that it already has made a +payment for in the past, and initiate **repurchase redirection**: Here, the +wallet will contact the merchant and replay the previous payment, except this +time using the (current) session ID of the browser (it learns the session ID +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 +existing paid contract. It then tells the browser to immediately redirect to +the fulfillment URL where the already paid article is available. + +To ensure this mechanism works as designed, merchants must make sure to not +use the same fulfillment URL for different products or for physical products +where customers may be expected to buy the article repeatedly. Similarly, +it is crucial that merchants consistently use the same fulfillment URL for +the same digital product where repurchase detection is desired. + +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 +considered to identify a resource you can pay for and thus do not have to be +unique. + + .. _Giving-Customers-Tips: +.. index:: tips Giving Customers Tips ===================== -tips 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 @@ -689,7 +757,3 @@ locations and they is also allowed to have additional fields. Contract renderers must render at least the fields listed above, and should render fields that they do not understand as a key-value list. - - -.. |image0| image:: arch-api.png - |