[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-merchant] branch master updated: API docs with one m
From: |
gnunet |
Subject: |
[GNUnet-SVN] [taler-merchant] branch master updated: API docs with one master file |
Date: |
Tue, 27 Feb 2018 22:55:15 +0100 |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] [taler-merchant] branch master updated: API docs with one master file,
gnunet <=