[GNUnet-SVN] [taler-merchant] branch master updated: API docs with one master file

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository merchant.

The following commit(s) were added to refs/heads/master by this push:
     new 3b7cda0  API docs with one master file
3b7cda0 is described below

commit 3b7cda05aacec2a6a722a6cb7bb2815fb438183e
Author: Florian Dold <address@hidden>
AuthorDate: Tue Feb 27 19:19:10 2018 +0100

    API docs with one master file
---
 .gitignore                    |   2 +-
 doc/Makefile.am               |  32 +-
 doc/manual.texi               |   2 +-
 doc/merchant-api-curl.texi    |  13 +
 doc/merchant-api-python.texi  |  13 +
 doc/merchant-api.content.texi | 684 ++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 737 insertions(+), 9 deletions(-)

diff --git a/.gitignore b/.gitignore
index cd4a016..83eb0af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,7 +39,7 @@ doc/*
 !doc/*.texi
 !doc/*.css
 !doc/*.1
-doc/version.texi
+doc/version-*.texi
 !doc/*.am
 !doc/*.sh
 !doc/*.js
diff --git a/doc/Makefile.am b/doc/Makefile.am
index a755143..7648399 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -3,10 +3,14 @@ all: manual.pdf manual.html
 manual.pdf: arch.pdf manual.texi
 manual.html: arch.png manual.texi
 
-arch.pdf: arch.dot
-       dot -Tpdf arch.dot > arch.pdf
-arch.png: arch.dot
-       dot -Tpng arch.dot > arch.png
+%.png: %.dot
+       dot -Tpng $< > $@
+%.pdf: %.dot
+       dot -Tpdf $< > $@
+
+merchant-api-%.%: merchant-api.content.texi
+merchant-api-%.pdf: arch-api.pdf
+html-local: arch-api.png
 
 AM_MAKEINFOHTMLFLAGS = --no-split --css-ref=docstyle.css 
--css-ref=brown-paper.css
 
@@ -14,14 +18,28 @@ man_MANS = \
   taler-merchant-generate-payments.1 \
   taler-merchant-httpd.1
 
-info_TEXINFOS = manual.texi
+info_TEXINFOS = \
+  manual.texi \
+  merchant-api-python.texi \
+  merchant-api-curl.texi
+
+manual_TEXINFOS = \
+  version-manual.texi \
+  merchant-api.content.texi
+
+merchant_api_python_TEXINFOS = \
+  version-merchant-api-python.texi \
+  merchant-api.content.texi
 
-manual_TEXINFOS = version.texi
+merchant_api_curl_TEXINFOS = \
+  version-merchant-api-curl.texi \
+  merchant-api.content.texi
 
 extra_TEXINFOS = \
   fdl-1.3.texi \
   agpl.texi \
-  syntax.texi
+  syntax.texi \
+  merchant-api.content.texi
 
 EXTRA_DIST = \
   arch.dot \
diff --git a/doc/manual.texi b/doc/manual.texi
index d8eeb0e..677f7de 100644
--- a/doc/manual.texi
+++ b/doc/manual.texi
@@ -1,7 +1,7 @@
 \input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename manual.info
address@hidden version.texi
address@hidden version-manual.texi
 @settitle The GNU Taler merchant backend operator tutorial @value{VERSION}
 
 @include syntax.texi
diff --git a/doc/merchant-api-curl.texi b/doc/merchant-api-curl.texi
new file mode 100644
index 0000000..32e9628
--- /dev/null
+++ b/doc/merchant-api-curl.texi
@@ -0,0 +1,13 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden merchant-api-curl.info
address@hidden version-merchant-api-curl.texi
address@hidden syntax.texi
address@hidden The GNU Taler Merchant API Tutorial @value{VERSION} for sh/cURL
+
address@hidden LANG_CURL 1
address@hidden LANGNAME sh/cURL
+
address@hidden merchant-api.content.texi
+
address@hidden
diff --git a/doc/merchant-api-python.texi b/doc/merchant-api-python.texi
new file mode 100644
index 0000000..7623a60
--- /dev/null
+++ b/doc/merchant-api-python.texi
@@ -0,0 +1,13 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden merchant-api-python.info
address@hidden version-merchant-api-python.texi
address@hidden syntax.texi
address@hidden The GNU Taler Merchant API Tutorial @value{VERSION} for Python
+
address@hidden LANG_PYTHON 1
address@hidden LANGNAME Python
+
address@hidden merchant-api.content.texi
+
address@hidden
diff --git a/doc/merchant-api.content.texi b/doc/merchant-api.content.texi
new file mode 100644
index 0000000..73d612a
--- /dev/null
+++ b/doc/merchant-api.content.texi
@@ -0,0 +1,684 @@
address@hidden *****************************************
address@hidden This file is supposed to be included from
address@hidden the language-specific tutorial.
address@hidden *****************************************
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Combine everything into one index (arbitrarily chosen to be the
address@hidden concept index).
address@hidden op cp
address@hidden %**end of header
+
address@hidden
+This document is a tutorial for the GNU Taler Merchant API (version 
@value{VERSION}, @value{UPDATED})
+
+Copyright @copyright{} 2018 Taler Systems SA
+
address@hidden
+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''.
address@hidden quotation
address@hidden copying
address@hidden If your tutorial is published on paper by the FSF, it should 
include
address@hidden The standard FSF Front-Cover and Back-Cover Texts, as given in
address@hidden maintain.texi.
address@hidden
address@hidden Titlepage
address@hidden
address@hidden
address@hidden The GNU Taler Merchant API tutorial 
address@hidden Version @value{VERSION}
address@hidden @value{UPDATED}
address@hidden Christian Grothoff (@email{christian@@grothoff.org})
address@hidden Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
address@hidden Florian Dold (@email{florian.dold@@inria.fr})
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
address@hidden
+
address@hidden
address@hidden Top
address@hidden The GNU Taler Merchant API Tutorial (Version for 
@value{LANGNAME})
address@hidden
address@hidden ifnottex
+
+
address@hidden
+* Introduction::                                  What this tutorial is about
+* Accepting a Simple Payment::                    How to accept simple payments
+* 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.
address@hidden menu
+
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden 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).
+
+
address@hidden About this tutorial
+
+This tutorial 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 proposal and process the payment.
+
address@hidden GOT_LANG
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
+This version of the tutorial has examples for Python3.
+It uses the requests library for HTTP requests.
address@hidden ifset
address@hidden LANG_CURL
address@hidden GOT_LANG 1
+This version of the tutorial has examples for the
+command line with cURL.
address@hidden ifset
address@hidden
+Versions for other languages/environments are available as well.
+
address@hidden examples
address@hidden git
+If you want to look at some simple, running examples, check out these:
address@hidden
address@hidden
+The @url{https://git.taler.net/blog.git/tree/talerblog/blog/blog.py, essay 
merchant} that
+sells single chapters of a book.
address@hidden
+The 
@url{https://git.taler.net/donations.git/tree/talerdonations/donations/donations.py,
 donation page} that
+accepts donations for software projects and gives donation receipts.
address@hidden
+The 
@url{https://git.taler.net/survey.git/tree/talersurvey/survey/survey.py,survey} 
that
+gives users who answer a question a small reward.
address@hidden itemize
+
address@hidden Architecture overview
+
+The Taler software stack for a merchant consists of the following
+main components:
+
address@hidden
address@hidden frontend
address@hidden 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.
address@hidden backend
address@hidden 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 sandbox backend.  For production
+  use, you must either set up your own backend or ask another person
+  to do so for you.
address@hidden itemize
+
+The following image illustrates the various interactions of these
+key components:
+
address@hidden, 3in}
+
+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.
+
+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 @code{/public/}.
+
address@hidden Public Sandbox Backend and Authentication
+
+How the frontend authenticates with the Taler backend depends in the 
configuration. @xref{Top,,, manual, Taler Merchant Operating Manual}.
+
+The public sandbox backend @url{https://backend.demo.taler.net} uses an API key
+in the @code{Authorization} header.  The value of this header must be
address@hidden sandbox} for the public sandbox backend.
+
address@hidden GOT_LANG
address@hidden LANG_CURL
address@hidden GOT_LANG 1
address@hidden
+$ curl -i 'https://backend.demo.taler.net/' --header "Authorization: ApiKey 
sandbox"
+# HTTP/1.1 200 OK
+# [...]
+#
+# Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
address@hidden example
address@hidden ifset
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
address@hidden
address@hidden
+>>> import requests
+>>> requests.get("https://backend.demo.taler.net";, headers={"Authorization": 
"ApiKey sandbox"})
+<Response [200]>
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden GOT_LANG
address@hidden
+(example not available for this language)
address@hidden example
address@hidden ifclear
+
+If an HTTP status code other than 200 is returned, something went wrong. You
+should figure out what the problem is before continuing with this tutorial.
+
+The sandbox backend @url{https://backend.demo.taler.net} uses @code{KUDOS} as
+an imaginary currency.  Coins denominated with @code{KUDOS} can be withdrawn
+from @url{https://bank.demo.taler.net}.
+
address@hidden Merchant Instances
+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 @emph{merchant instance}, and is identified by an
+alphanumeric @emph{instance id}.  If the instance is omitted, the instance id
address@hidden is assumed.
+
+The following merchant instances are configured on 
@url{https://backend.demo.taler.net}:
address@hidden
address@hidden @code{GNUnet} (The GNUnet project)
address@hidden @code{FSF} (The Free Software Foundation)
address@hidden @code{Tor} (The Tor Project)
address@hidden @code{default} (Kudos Inc.)
address@hidden itemize
+
+Note that these are fictional merchants and not necessarily affiliated with the
+respective project.
+
+
address@hidden Accepting a Simple Payment
address@hidden Accepting a Simple Payment
+
address@hidden Creating an Order for a Payment
+
+Payments in Taler revolve around an @emph{order}, which is a machine-readable
+description of the payment's details.  Before accepting a Taler payment as a 
merchant
+you must create an order.
+
+This is done by posting a JSON object to the backend's @code{/order} API 
endpoint.  At least the
+following fields must be given:
+
address@hidden
address@hidden @var{amount}: The amount to be paid, as a string in the format
address@hidden:VALUE}, for example @code{EUR:10} for 10 Euros or
address@hidden:1.5} for 1.5 KUDOS.
+
address@hidden @var{summary}:  A human-readable summary for what the payment is 
about,
+should be short enough to fit into titles, though currently no hard limit is
+enforced.
+
address@hidden @var{fulfillment_url}:  A URL that will be displayed once the 
payment is
+completed.  For digital goods, this should be a page that displays the product
+that was purchased.
address@hidden itemize
+
+After successfully POSTing to @code{/order}, an @code{order_id} will be
+returned.  Together with the @code{instance id}, the order id uniquely
+identifies the order within a merchant backend.
+
address@hidden GOT_LANG
address@hidden LANG_CURL
address@hidden GOT_LANG 1
address@hidden
address@hidden
+$ ORDER='
+{"order": {
+  "amount": "KUDOS:10",
+  "summary": "Donation",
+  "fulfillment_url": "https://example.com/thanks.html"}}
+'
+
+$ curl -i -X POST 'https://backend.demo.taler.net/order' --header 
"Authorization: ApiKey sandbox" -d "$ORDER"
+# HTTP/1.1 200 OK
+# [...]
+#
+# {
+#   "order_id": "2018.058.21.46.06-024C85K189H8P"
+# }
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
address@hidden
address@hidden
+>>> import requests
+>>> order = dict(order=dict(amount="KUDOS:10",
+...                         summary="Donation",
+...                         fulfillment_url="https://example.com/thanks.html";))
+>>> requests.get("https://backend.demo.taler.net";, headers={"Authorization": 
"ApiKey sandbox"})
+<Response [200]>
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden GOT_LANG
address@hidden
+(example not available for this language)
address@hidden example
address@hidden ifclear
+
+The backend will fill in some details missing in the order, such as the address
+of the merchant instance.  The full details are often called the @emph{contract
+terms}.
+
address@hidden Checking Payment Status and Prompting for Payment
+The status of a payment can be checked with the @code{/check-payment} 
endpoint.  If the payment
+wasn't completed yet by the customer, @code{/check-payment} will give the 
frontend a URL (@var{payment_redirect_url})
+that will trigger the customer's wallet to trigger the payment.
+
+Note that the only way to obtain the @var{payment_redirect_url} is to check 
the status of the payment,
+even if you know that the user did not pay yet.
+
address@hidden GOT_LANG
address@hidden LANG_CURL
address@hidden GOT_LANG 1
address@hidden
address@hidden
+curl -i 
'https://backend.demo.taler.net/check-payment?order_id=2018.058.21.46.06-024C85K189H8P'
 --header "Authorization: ApiKey sandbox"
+# HTTP/1.1 200 OK
+# [...]
+# 
+# {
+#   "payment_redirect_url": 
"https://backend.demo.taler.net/public/trigger-pay?[...]";,
+#   "paid": false
+# }
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden LANG_PYTHON
address@hidden GOT_LANG 1
address@hidden
address@hidden
+>>> import requests
+>>> r = requests.get("https://backend.demo.taler.net/check-payment";,
+...                  params=dict(order_id=order_id),
+...                  headers={"Authorization": "ApiKey sandbox"})
+>>> print(r.json())
address@hidden verbatim
address@hidden example
address@hidden ifset
address@hidden GOT_LANG
address@hidden
+(example not available for this language)
address@hidden example
address@hidden ifclear
+
+Depending on the value of the @var{paid} field in the response, the other 
fields will be different.  Once the
+payment was completed by the user, the response will contain the following 
fields:
+
address@hidden
address@hidden @var{paid}: Set to @var{true}.
address@hidden @var{contract_terms}:  The full contract terms derived from the 
order.
address@hidden @var{refunded}:  Boolean that indicates whether any (partial) 
refund happened for this purchase.
address@hidden @var{refunded_amount}:  Amount that was refunded
address@hidden @var{last_session_id}:  Last session ID used by the customer's 
wallet.  Advanced feature, explained later.
address@hidden itemize
+
+
address@hidden Back-office-integration
address@hidden 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}.
+
address@hidden Advanced topics
address@hidden Advanced topics
+
address@hidden
+* Detecting the Presence of the Taler Wallet::  Detecting the Presence of the 
Taler Wallet
+* The Taler Order Format::                      The Taler Order Format
address@hidden menu
+
address@hidden Detecting the Presence of the Taler Wallet
address@hidden Detecting the Presence of the Taler Wallet
address@hidden wallet
+
+Taler offers the way to the frontend developer to detect whether
+a user has the wallet installed in their browser, and take actions
+accordingly.
+
address@hidden The no-JavaScript way
+The follwing example shows all that is needed to perform the detection
+without using JavaScript:
+
address@hidden
+<!DOCTYPE html>
+<html data-taler-nojs="true">
+  <head>
+    <title>Tutorial</title>
+    <link rel="stylesheet"
+          type="text/css"
+          href="/web-common/taler-fallback.css"
+          id="taler-presence-stylesheet" />
+  </head>
+  <body>
+    <p class="taler-installed-hide">
+      No wallet found.
+    </p>
+    <p class="taler-installed-show">
+      Wallet found!
+    </p>
+  </body>
+</html>
address@hidden smallexample
+
+The @code{taler-fallback.css} is part of the Taler's @emph{web-common} 
repository,
+available at @code{https://git.taler.net/web-common.git}.  Please adjust the 
@code{href}
+attribute in order to make it work with your Web site.
+
+The detection works by @code{taler-fallback.css} hiding any tag from the
address@hidden class, in case no wallet is installed.  If otherwise
+the wallet is installed, the wallet takes action by hiding any tag from the
address@hidden class and overriding @code{taler-fallback.css} logic
+by showing any tag from the @code{taler-installed-show} class.
+
address@hidden The JavaScript way
+
address@hidden helps the frontend, by providing the way to register two
+callbacks: one to be executed if a wallet is present, the other if it is not.
+See the example below:
+
address@hidden
address@hidden smallexample
+
address@hidden exports the @code{taler} object that
+exposes the @code{onPresent} and the @code{onAbsent} functions needed
+to register the frontend's callbacks.  Thus the function @code{walletInstalled}
+will be executed whenever a wallet is installed, and @code{walletNotInstalled}
+if not.  Note that since now we can use JavaScript we can register
+callbacks that do more than just showing and hiding elements.
+
+
address@hidden Section describing the format of Taler contracts/proposals in 
detail
+
address@hidden The Taler Order Format
address@hidden The Taler Order Format
address@hidden contract
+
+A Taler order can specify many details about the payment.
+This section describes each of the fields in depth.
+
address@hidden @var
address@hidden amount
address@hidden amount
+Specifies the total amount to be paid to the merchant by the customer.
+
address@hidden max_fee
address@hidden fees
address@hidden maximum deposit fee
+This is the maximum total amount of deposit fees that the merchant is
+willing to pay.  If the deposit fees for the coins exceed this amount,
+the customer has to include it in the payment total.  The fee is
+specified using the same triplet used for @var{amount}.
+
+
address@hidden max_wire_fee
address@hidden fees
address@hidden maximum wire fee
+Maximum wire fee accepted by the merchant (customer share to be
+divided by the 'wire_fee_amortization' factor, and further reduced
+if deposit fees are below 'max_fee').  Default if missing is zero.
+
+
address@hidden wire_fee_amortization
address@hidden fees
address@hidden maximum fee amortization
+Over how many customer transactions does the merchant expect to
+amortize wire fees on average?  If the exchange's wire fee is
+above 'max_wire_fee', the difference is divided by this number
+to compute the expected customer's contribution to the wire fee.
+The customer's contribution may further be reduced by the difference
+between the 'max_fee' and the sum of the actual deposit fees.
+Optional, default value if missing is 1.  0 and negative values are
+invalid and also interpreted as 1.
+
address@hidden pay_url
address@hidden pay_url
+Which URL accepts payments. This is the URL where the wallet will POST
+coins.
+
address@hidden fulfillment_url
address@hidden fulfillment URL
+Which URL should the wallet go to for obtaining the fulfillment,
+for example the HTML or PDF of an article that was bought, or an
+order tracking system for shipments, or a simple human-readable
+Web page indicating the status of the contract.
+
address@hidden order_id
address@hidden order ID
+Alphanumeric identifier, freely definable by the merchant.
+Used by the merchant to uniquely identify the transaction.
+
address@hidden summary
address@hidden summary
+Short, human-readable summary of the contract. To be used when
+displaying the contract in just one line, for example in the
+transaction history of the customer.
+
address@hidden timestamp
+Time at which the offer was generated.
address@hidden FIXME: describe time format in detail here
+
address@hidden pay_deadline
address@hidden payment deadline
+Timestamp of the time by which the merchant wants the exchange
+to definitively wire the money due from this contract.  Once
+this deadline expires, the exchange will aggregate all
+deposits where the contracts are past the @var{refund_deadline}
+and execute one large wire payment for them.  Amounts will be
+rounded down to the wire transfer unit; if the total amount is
+still below the wire transfer unit, it will not be disbursed.
+
address@hidden refund_deadline
address@hidden refund deadline
+Timestamp until which the merchant willing (and able) to give refunds
+for the contract using Taler.  Note that the Taler exchange will hold
+the payment in escrow at least until this deadline.  Until this time,
+the merchant will be able to sign a message to trigger a refund to the
+customer.  After this time, it will no longer be possible to refund
+the customer.  Must be smaller than the @var{pay_deadline}.
+
address@hidden products
address@hidden product description
+Array of products that are being sold to the customer.  Each
+entry contains a tuple with the following values:
+
address@hidden @var
address@hidden description
+Description of the product.
address@hidden quantity
+Quantity of the items to be shipped. May specify a unit (@code{1 kg})
+or just the count.
address@hidden price
+Price for @var{quantity} units of this product shipped to the
+given @var{delivery_location}. Note that usually the sum of all
+of the prices should add up to the total amount of the contract,
+but it may be different due to discounts or because individual
+prices are unavailable.
address@hidden product_id
+Unique ID of the product in the merchant's catalog.  Can generally
+be chosen freely as it only has meaning for the merchant, but
+should be a number in the range @math{[0,2^{51})}.
address@hidden taxes
+Map of applicable taxes to be paid by the merchant.  The label is the
+name of the tax, i.e. @var{VAT}, @var{sales tax} or @var{income tax},
+and the value is the applicable tax amount.  Note that arbitrary
+labels are permitted, as long as they are used to identify the
+applicable tax regime.  Details may be specified by the regulator.
+This is used to declare to the customer which taxes the merchant
+intends to pay, and can be used by the customer as a receipt.
address@hidden FIXME: a receipt not including the item's price?
+The information is also likely to be used by tax audits of the merchant.
address@hidden delivery_date
+Time by which the product is to be delivered to the
address@hidden
address@hidden delivery_location
+This should give a label in the @var{locations} map, specifying
+where the item is to be delivered.
address@hidden table
+Values can be omitted if they are not applicable. For example, if a
+purchase is about a bundle of products that have no individual prices
+or product IDs, the @var{product_id} or @var{price} may not be
+specified in the contract.  Similarly, for virtual products delivered
+directly via the fulfillment URI, there is no delivery location.
+
address@hidden merchant
address@hidden @var
address@hidden address
+This should give a label in the @var{locations} map, specifying
+where the merchant is located.
address@hidden name
+This should give a human-readable name for the merchant's business.
address@hidden jurisdiction
+This should give a label in the @var{locations} map, specifying
+the jurisdiction under which this contract is to be arbitrated.
address@hidden table
+
address@hidden locations
address@hidden location
+Associative map of locations used in the contract. Labels for
+locations in this map can be freely chosen and used whenever
+a location is required in other parts of the contract.  This way,
+if the same location is required many times (such as the business
+address of the customer or the merchant), it only needs to be
+listed (and transmitted) once, and can otherwise be referred to
+via the label.  A non-exhaustive list of location attributes
+is the following:
address@hidden @var
address@hidden country
+Name of the country for delivery, as found on a postal package, i.e. 
``France''.
address@hidden state
+Name of the state for delivery, as found on a postal package, i.e. ``NY''.
address@hidden region
+Name of the region for delivery, as found on a postal package.
address@hidden province
+Name of the province for delivery, as found on a postal package.
address@hidden city
+Name of the city for delivery, as found on a postal package.
address@hidden ZIP code
+ZIP code for delivery, as found on a postal package.
address@hidden street
+Street name for delivery, as found on a postal package.
address@hidden street number
+Street number (number of the house) for delivery, as found on a postal package.
address@hidden name receiver name for delivery, either business or person name.
+
address@hidden table
+
+Note that locations are not required to specify all of these fields,
+and it 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.
+
address@hidden table
+
+
address@hidden Reference
address@hidden Reference
+
address@hidden
+* JavaScript API::                       JavaScript API to communicate with 
the wallet
+* Stylesheet-based presence detection::  Presence detection using CSS style 
sheets and no JavaScript
address@hidden menu
+
address@hidden JavaScript API
address@hidden JavaScript API
+
+The following functions are defined in the @code{taler} namespace of the 
@code{taler-wallet-lib} helper library
+available at 
@url{https://git.taler.net/web-common.git/tree/taler-wallet-lib.js}.
+
address@hidden @code
address@hidden onPresent(callback: () => void)
+Add a callback to be called when support for Taler payments is detected.
+
address@hidden onAbsent(callback: () => void)
+Add a callback to be called when support for Taler payments is disabled.
+
address@hidden pay(@{contract_url: string, offer_url: address@hidden)
+Results in the same action as a @code{402 Payment Required} with 
@code{contract_url} in
+the @code{X-Taler-Contract-Url} header and @code{offer_url} in the 
@code{X-Taler-Payment-Url} header.
+
address@hidden refund(refund_url: string)
+Results in the same action as a @code{402 Payment Required} with 
@code{refund_url} in
+the @code{X-Taler-Refund-Url} header.
+
address@hidden table
+
address@hidden Stylesheet-based presence detection
address@hidden Stylesheet-based presence detection
+
+Stylesheet-based presence detection will be applied on all pages that have the
address@hidden attribute of the @code{html} element set @code{true}.
+The default/fallback stylesheet, that will be taken over by the wallet once
+installed, must be included with the id @code{taler-presence-stylesheet}, like
+this:
+
+The following CSS classes can be used:
address@hidden @code
address@hidden taler-installed-hide
+A CSS rule will set the @code{display} property for this class to @code{none} 
once the Taler wallet is installed and enabled.
+If the wallet is not installed, @code{display} will be @code{inherit}.
+
address@hidden taler-installed-show
+A CSS rule will set the @code{display} property for this class to 
@code{inherit} once the Taler wallet is installed and enabled.
+If the wallet is not installed, @code{display} will be @code{none}.
+
address@hidden table
+
+
+
address@hidden **********************************************************
address@hidden *******************  Appendices  *************************
address@hidden **********************************************************
+
address@hidden GNU-LGPL
address@hidden GNU-LGPL
address@hidden license
address@hidden LGPL
address@hidden lgpl.texi
+
address@hidden GNU-FDL
address@hidden GNU-FDL
address@hidden license
address@hidden GNU Free Documentation License
address@hidden fdl-1.3.texi
+
address@hidden Concept Index
address@hidden Concept Index
+
address@hidden cp

-- 
To stop receiving notification emails like this one, please contact
address@hidden