merchant-frontend-examples

tutorial.texi (19924B)

---

 \input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename tutorial.info
 @include ../../common/texi/version.texi
 @include ../../common/texi/syntax.texi
 @settitle The GNU Taler tutorial for Python Web shop developers @value{VERSION}
 
 @c Define a new index for options.
 @defcodeindex op
 @c Combine everything into one index (arbitrarily chosen to be the
 @c concept index).
 @syncodeindex op cp
 @c %**end of header
 
 @copying
 This tutorial is about implementing a merchant frontend to run against a
 GNU Taler merchant backend (version @value{VERSION}, @value{UPDATED}),
 
 Copyright @copyright{} 2016, 2017, 2018 Taler Systems SA
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled
 ``GNU Free Documentation License''.
 @end quotation
 @end copying
 @c If your tutorial is published on paper by the FSF, it should include
 @c The standard FSF Front-Cover and Back-Cover Texts, as given in
 @c maintain.texi.
 @c
 @c Titlepage
 @c
 @titlepage
 @title The GNU Taler tutorial for Python Web shops
 @subtitle Version @value{VERSION}
 @subtitle @value{UPDATED}
 @author Christian Grothoff (@email{christian@@grothoff.org})
 @author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
 @author Florian Dold (@email{florian.dold@@inria.fr})
 @page
 @vskip 0pt plus 1filll
 @insertcopying
 @end titlepage
 
 @summarycontents
 @contents
 
 @ifnottex
 @node Top
 @top The GNU Taler tutorial for Python Web shops
 @insertcopying
 @end ifnottex
 
 @menu
 * Introduction::                                  What this tutorial is about
 * Setting up a simple donation page::             How to set up a donation page
 * Back-office-integration::                       How to integrate with the back office
 * Advanced topics::                               Detailed solutions to specific issues
 * Reference::                                     Merchant integration reference
 
 
 Appendices
 
 * GNU-LGPL::                     The GNU Lesser General Public License says how you
                                  can use the code of libtalermerchant.so in your own projects.
 * GNU-FDL::                      The GNU Free Documentation License says how you
                                  can copy and share the documentation of GNU Taler.
 
 Indices
 
 * Concept Index::               Index of concepts and programs.
 @end menu
 
 
 @node Introduction
 @chapter Introduction
 
 @section About GNU Taler
 
 GNU Taler is an open protocol for an electronic payment system with a
 free software reference implementation.  GNU Taler offers secure, fast
 and easy payment processing using well understood cryptographic
 techniques.  GNU Taler allows customers to remain anonymous, while
 ensuring that merchants can be held accountable by governments.
 Hence, GNU Taler is compatible with anti-money-laundering (AML) and
 know-your-customer (KYC) regulation, as well as data protection
 regulation (such as GDPR).
 
 
 @section About this tutorial
 
 This tutorial is for Python Web developers and addresses how to integrate GNU
 Taler with Web shops. It describes how to create a Web shop that
 processes payments with the help of a GNU Taler merchant
 @emph{backend}.   In the second chapter, you will learn how to trigger
 the payment process from the Web site, how to communicate with the
 backend, how to generate a order and process the payment.  The
 third chapter covers the integration of a back office with the
 backend, which includes tracking payments for orders, matching
 payments to orders, and persisting and retrieving contracts.
 
 @cindex examples
 @cindex git
 You can download all of the code examples given in this tutorial from
 @url{https://git.taler.net/merchant-frontend-examples.git/tree/python/example/}.
 
 
 @section Architecture overview
 
 The Taler software stack for a merchant consists of the following
 main components:
 
 @itemize
 @cindex frontend
 @item A frontend which interacts with the customer's browser. The
   frontend enables the customer to build a shopping cart and place
   an order.  Upon payment, it triggers the respective business logic
   to satisfy the order.  This component is not included with Taler,
   but rather assumed to exist at the merchant. This tutorial
   describes how to develop a Taler frontend.
 @cindex back office
 @item A back office application that enables the shop operators to
   view customer orders, match them to financial transfers, and possibly
   approve refunds if an order cannot be satisfied.  This component is
   again not included with Taler, but rather assumed to exist at the
   merchant. This tutorial will describe how to integrate such a component
   to handle payments managed by Taler.  Such integration is shown by
   adding the back office functionality to the frontend implemented
   in the second part of this tutorial.
 @cindex backend
 @item A Taler-specific payment backend which makes it easy for the
   frontend to process financial transactions with Taler.  For this
   tutorial, you will use a public backend, but for a production
   deployment a merchant-specific backend will need to be setup
   by a system administrator.
 @end itemize
 
 The following image illustrates the various interactions of these
 key components:
 
 @image{arch_nobo, 3in, 4in}
 
 
 The backend provides the cryptographic protocol support,
 stores Taler-specific financial information and communicates
 with the GNU Taler exchange over the Internet.  The frontend accesses
 the backend via a RESTful API.  As a result, the frontend never has to
 directly communicate with the exchange, and also does not deal with
 sensitive data.  In particular, the merchant's signing keys and bank
 account information are encapsulated within the Taler backend.
 
 
 @node Setting up a simple donation page
 @chapter Setting up a simple donation page
 
 This section describes how to setup a simple shop, which exposes a
 button to get donations via Taler. The expected behaviour is that once
 the ``donate'' button is clicked, the customer will receive a
 proposal to make a fixed donation,
 for example to donate 1.0 KUDOS to the charity operating the shop.
 
 All the code samples shown below in the tutorial can be found at
 @url{https://git.taler.net/merchant-frontend-examples.git/tree/python/example/}.
 Each sample is part of a functional frontend.
 The language is Python, and the Web is served by
 Flask@footnote{http://flask.pocoo.org/}.
 
 @c NOTE: include explaining wallet installation to Web developer here!
 
 @c Next sentence is inconsistent with PHP version. Why?
 An error message will be shown to the user if no Taler wallet is
 installed in the browser.
 
 @section Specifying the backend
 
 @cindex backend
 @cindex configuration
 @cindex currency
 For many critical operations, the frontend needs to communicate
 with a Taler backend. Assuming that you do not yet have a backend
 configured@footnote{https://docs.taler.net/current/merchant-backend/manual.html},
 you can use the public backend provided by the Taler
 project for testing.  This public backend has been set-up at
 @code{http://backend.test.taler.net/} specifically for testing
 frontends.  It uses the currency ``TESTKUDOS'' and all payments will
 go into the ``Tutorial'' account at the Taler ``bank'' running at
 @code{https://bank.test.taler.net/public-accounts}.
 
 In our example, backend and currency are specified by setting two
 global variables, as shown below from @code{python/example/example.py}:
 
 @smallexample
 ..
 CURRENCY = "TESTKUDOS"
 BACKEND_URL = "http://backend.test.taler.net/"
 ..
 @end smallexample
 
 
 @section Talking to the backend
 
 @cindex backend
 The frontend needs to issue HTTP POST requests to the backend; this can be
 done using the @emph{requests}@footnote{https://docs.taler.net/current/merchant-backend/manual.html}
 library:
 
 @smallexample
 import flask
 import requests
 from urllib.parse import urljoin
 ..
 
 # In this example we use the /proposal API offered by the
 # backend, which is in charge of signing orders.
 r = requests.post(urljoin(BACKEND_URL, 'proposal'), json=dict(order=order))
 
 if r.status_code != 200:
     logger.error("failed to POST to '%s'", url)
     return r.text, r.status_code
 @end smallexample
 
 
 @section Prompting for payment
 
 @cindex button
 Our goal is to trigger a Taler payment once the customer has clicked
 on a donation button.  We will use a button that issues an HTTP GET
 to the frontend @code{/donate} URL.  For this, the HTML would be as
 follows:
 
 @smallexample
 <!-- ../example/templates/index.html -->
 @verbatiminclude ../example/templates/index.html
 @end smallexample
 
 When the server-side handler for @code{/donate} receives the form submission,
 it will return a HTML page and HTTP header that will take care of:
 
 @itemize
 @item showing a error message if no wallet is installed
 @item instruct the wallet to download the proposal related to this donation
 @end itemize
 
 The @code{/donate} endpoint looks like this:
 
 @cindex pay handler
 @cindex 402
 @cindex X-Taler-Contract-Url
 @smallexample
 @@app.route("/donate")
 def donate():
    response = flask.Response("No wallet installed!", status=402)
    response.headers["X-Taler-Contract-Url"] = "/generate-proposal"
    return response
 @end smallexample
 The wallet detects the 402 status and reacts by downloading
 the proposal from @code{/generate-proposal}.  The proposal
 is then presented to the user.
 
 If the wallet is not present, the error message ``No wallet
 installed!'' will be shown and the Taler ``X-Taler-Contract-Url''
 header and the 402 status code ought to be ignored by the browser.
 
 @section A helper function to generate the order
 
 We make distinction between @emph{three} different stages of what it
 informally called "contract".
 
 In a very first stage, we call it the @emph{order}: that occurs when
 the frontend generates the first JSON that misses some information
 that the backend is supposed to add.  When the backend completes the
 order and signs it, we have a @emph{proposal}.  The proposal is what
 the user is prompted with, and allows them to confirm the purchase.
 Once the user confirms the purchase, the wallet makes a signature over
 the proposal, turning it into a @emph{contract}.
 
 The next step is to generate a proposal whenever the wallet makes a GET
 @code{/generate-proposal} request.  In our example, this logic is implemented
 by the function @code{generate_proposal()}:
 
 @c FIXME: rename package to just 'taler' or 'gnu.taler'? (Check with Florian)
 @cindex contract
 @cindex proposal
 @cindex order
 @smallexample
 ..
 from pytaler import amount
 ..
 @@app.route("/generate-proposal")
 def generate_proposal():
     DONATION = amounts.string_to_amount("0.1:%s" % CURRENCY)
     MAX_FEE = amounts.string_to_amount("0.05:%s" % CURRENCY)
     ORDER_ID = "tutorial-%X-%s" % (randint(0, 0xFFFFFFFF), datetime.today().strftime("%H_%M_%S"))
     order = dict(
         nonce=flask.request.args.get("nonce"),
         order_id=ORDER_ID,
         amount=DONATION,
         max_fee=MAX_FEE,
         products=[
             dict(
                 description="Donation",
                 quantity=1,
                 product_id=0,
                 price=DONATION,
             ),
         ],
         fulfillment_url=make_url("/fulfillment", ("order_id", ORDER_ID)),
         pay_url=make_url("/pay"),
         merchant=dict(
             address="nowhere",
             name="Donation tutorial",
             jurisdiction="Ursa Minor",
         ),
     )
 
     url = urljoin(BACKEND_URL, "proposal")
 
     r = requests.post(url, json=dict(order=order))
     if r.status_code != 200:
         logger.error("failed to POST to '%s'", url)
         return r.text, r.status_code
     proposal_resp = r.json()
     return flask.jsonify(**proposal_resp)
 @end smallexample
 @c CHECK ** with Florian, consider inlining...
 
 The function @code{amounts.string_to_amount()} is defined by the
 @emph{pytaler} library, and it is used to convert amounts given as strings
 (in the form @code{"1.2:EUR"}) to amount as `dict` (in the form
 @code{@{value:1, fraction:20000000, currency:"EUR"@}}).
 @cindex signature
 @cindex backend
 @cindex proposal
 One important thing that @code{generate_proposal()} needs to do is to
 POST the ``order'' to the backend.  This is needed because the backend
 has to fill some missing fields and sign the whole order; once the backend
 has done that, it returns the completed data and its signature to the
 frontend that can eventually relay it to the wallet.
 
 The @code{make_url} function is used to ``attach'' paths to the shop's
 base URL.  For example, if the shop is run at @code{https://shop.com},
 then @code{make_url("/path", ("a", 5))} would result in @code{https://shop.com/path?a=5}.
 
 
 @section Initiating the payment process
 
 @cindex fulfillment URL
 After the wallet has fetched the proposal, the user will be
 given the opportunity to affirm the payment.  Assuming the user
 affirms, the browser will navigate to the ``fulfillment_url'' that
 was specified in the offer.
 
 The fulfillment page can be called by users that have already paid for
 the item, as well as by users that have not yet paid at all.  The
 fulfillment page must thus use the HTTP session state to detect if the
 payment has been performed already, and if not request payment from
 the wallet.
 
 The fulfillment handler at @code{/fulfillment} must thus first figure out
 if the user has already paid, and if so merely confirm the donation.
 If the user has not yet paid, it must instead return another ``402 Payment
 Required'' header, requesting the wallet to pay:
 
 @cindex 402 payment required
 @smallexample
 @@app.route("/fulfillment")
 def fulfillment():
     # Ask the state whether the user has paid or not
     paid = flask.session.get("paid", False)
     if paid:
         # Please note that flask.session["order_id"] takes its value
         # from the response the _backend_ gave for /pay. This way, the fulfillment
         # page only shows what the wallet paid for.
         return "Thank you! Your order id is: <b>%s</b>." % flask.session["order_id"]"
 
     # At this point, the user did not pay yet, so we set some
     # appropriate HTTP headers that will instruct the wallet to
     # make the payment, assuming the user already accepted the
     # proposal.
     response = flask.Response(status=402)
 
     # At this URL, the wallet may request a regeneration of the proposal.
     response.headers["X-Taler-Contract-Url"] = make_url("/generate-proposal")
     # This URL will be visited in case the user has opened
     # on someone else's fulfillment URL.  As a result, the
     # user will be offered a fresh proposal.
     response.headers["X-Taler-Offer-Url"] = make_url("/donate")
 
     return response
 @end smallexample
 @c FIXME: check with Florian: isn't 'x-taler-contract-query' dead by now?
 
 The @code{X-Taler-Contract-Query} header is crucial for implementing replayable
 payments.  In fact, upon receiving such a header, the wallet will look in its
 internal database if a payment to the current fulfillment URL has already been
 sent.  If that's the case, then the coins from that previous payment will be
 sent to the @emph{pay_url}.
 That is exactly what happens when the user visits some bookmarked fulfillment
 page in order to see again what they already paid for.
 That header is scheduled to be removed in future versions of the wallet,
 as it only works with the value @code{"fulfillment_url"}.
 
 @section Receiving payments via Taler
 
 The final next step for the frontend is to receive the payment from the
 wallet.  For this, the frontend must implement a payment handler at
 the URI specified in the @code{pay_url} field of the proposal, so @code{/pay}
 in our example.
 
 The role of the @code{/pay} handler is to receive the payment
 from the wallet and forward it to the backend.  The backend
 executes the payment.  If it reports that the payment was successful
 by returning a "200 OK" status code, the handler needs to update
 the session state with the browser to remember that the user paid.
 If the backend reports a failure, the error response is passed on to
 the wallet.
 
 In our example, that is done by the @code{pay} function; see below.
 
 @smallexample
 @@app.route("/pay", methods=["POST"])
 def pay():
     # Here we get the payment from the wallet.  The
     # "payment" is a JSON containing coins and proposal
     # signed by the wallet, plus some other metadata.
     deposit_permission = flask.request.get_json()
     if deposit_permission is None:
         e = flask.jsonify(error="no json in body")
         return e, 400
 
     # Forwarding the payment to the backend that will cryptographically
     # verify it and persist the proof of payment.
     r = requests.post(urljoin(BACKEND_URL, 'pay'), json=deposit_permission)
 
     # Pass errors back to the wallet.
     if 200 != r.status_code:
         return r.text, r.status_code
 
     # The payment went through, so we can set the state as "paid".
     # Note that once this page will return "200 OK", the wallet will
     # automatically re-visit the fulfillment page (and get the "Thank
     # you" message this time).
     flask.session["paid"] = True
 
     return flask.Response(status=200)
 @end smallexample
 
 
 @section Running the Example
 
 The example depends on the @code{pytaler} library. The next commands
 show how to install it:
 
 @smallexample
 $ cd python/lib/
 $ export TALER_PREFIX=<YOUR-PREFIX>
 $ make install
 @end smallexample
 
 Make sure your python code will look for libraries within the
 @code{<YOUR-PREFIX>} directory.
 
 The file @code{python/example/example.py} contains all the code samples
 seen so far, incuding the @code{make_url()} helper function.
 It is run as a typical Flask application, using the following commands:
 
 @smallexample
 $ cd python/example/
 $ export FLASK_APP=example.py
 $ flask run
 @end smallexample
 
 At this point you should have the site running at @code{localhost} on port 5000.
 
 To do a test payment, you first need to visit
 @code{https://taler.net/wallet} from where you can install the Taler
 wallet.  Then, you need to withdraw a few coins from our demonstration
 bank running at @code{https://bank.test.taler.net/}.  After that, you
 should be able to point your browser at @code{http://localhost:5000/}
 and make a donation.
 
 @node Back-office-integration
 @chapter Integration with the back office
 
 Taler ships the back-office feature as a stand-alone Web application.
 See how to run it, on its own documentaion: @url{https://docs.taler.net/backoffice/html/manual.html}.
 
 @node Advanced topics
 @chapter Advanced topics
 
 @menu
 * Detecting the presence of the Taler wallet::  Detecting the presence of the Taler wallet
 * The Taler proposal format::                   The Taler proposal format
 @c * Inline proposals::                            Sending proposals with the HTTP header
 * Instances::                                   Instances
 * The fulfillment page::                        The fulfillment page
 * Normalized base URLs::                        Normalized base URLs
 @end menu
 
 @include ../../common/texi/wallet-detection.texi
 @include ../../common/texi/proposals.texi
 @c @include inline-proposals.texi  -- not yet written for Python!
 @include ../../common/texi/instances.texi
 @include ../../common/texi/fulfillment-page.texi
 @include ../../common/texi/normalized-base-url.texi
 
 
 
 @c ************ Reference chapter ***********
 @include ../../common/texi/api-reference.texi
 
 
 
 @c **********************************************************
 @c *******************  Appendices  *************************
 @c **********************************************************
 
 @node GNU-LGPL
 @unnumbered GNU-LGPL
 @cindex license
 @cindex LGPL
 @include ../../common/texi/lgpl.texi
 
 @node GNU-FDL
 @unnumbered GNU-FDL
 @cindex license
 @cindex GNU Free Documentation License
 @include ../../common/texi/fdl-1.3.texi
 
 @node Concept Index
 @unnumbered Concept Index
 
 @printindex cp
 
 @bye