1 files changed, 88 insertions, 0 deletions
diff --git a/common/texi/api-reference.texi b/common/texi/api-reference.texi
new file mode 100644
index 0000000..6e3cd52
--- /dev/null
+++ b/common/texi/api-reference.texi
@@ -0,0 +1,88 @@
+@node Reference
+@chapter Reference
+
+@menu
+* Headers for HTTP 402::                 Headers for the 402 status code and their effect on the user agent's operation
+* JavaScript API::                       JavaScript API to communicate with the wallet
+* Stylesheet-based presence detection::  Presence detection using CSS style sheets and no JavaScript
+@end menu
+
+@node Headers for HTTP 402
+@section Headers for HTTP 402
+The HTTP status code @code{402 Payment Required} can be used by the merchant
+frontend to trigger operations related to payments in the user agent.  The user
+agent associates at most one proposal with every URL via the proposal's
+@code{fulfillment_url} field.  The associated proposal is either missing (in
+case it doesn't exist), paid (in case the payment for it was successfully sent
+to the merchant) or unpaid.  If the associated proposal is unpaid,  @code{402
+Payment Required} will cause the user agent to pay for the associated proposal.
+
+The following headers for @code{402 Payment Required} are recognized by Taler and further influence the processing:
+@table @code
+@item X-Taler-Refund-Url
+If this header present, the value of this header must be a URL that the user agent can use to request and process refunds.
+
+@item X-Taler-Contract-Url
+If there is no associated proposal, the user agent will fetch a proposal from
+this URL and process it.  This typically prompts the user to agree to pay.
+
+@item X-Taler-Offer-Url
+If there is no associated proposal and @code{X-Taler-Contract-Url} is not
+specified, the browser will navigate to this URL.
+
+@item X-Taler-User-Tipping-Url
+If this header present, the value of this header must be a URL that the user agent can use to obtain tips (small, non-binding
+financial rewards) payed from the merchant to the user's wallet.  If this field is present, @code{X-Taler-User-Tipping-Exchange}
+and @code{X-Taler-User-Tipping-Amount} must also be present.
+
+@item X-Taler-User-Tipping-Exchange
+Exchange base URL for the exchange that the merchant helps withdrawing the tip from.
+
+@item X-Taler-User-Tipping-Amount
+Amount of tip that the user is receiving, in the standard amount format (CURR:X.Y).
+
+@end table
+
+@node JavaScript API
+@section 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}.
+
+@table @code
+@item onPresent(callback: () => void)
+Add a callback to be called when support for Taler payments is detected.
+
+@item onAbsent(callback: () => void)
+Add a callback to be called when support for Taler payments is disabled.
+
+@item pay(@{contract_url: string, offer_url: string@})
+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.
+
+@item 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.
+
+@end table
+
+@node Stylesheet-based presence detection
+@section Stylesheet-based presence detection
+
+Stylesheet-based presence detection will be applied on all pages that have the
+@code{data-taler-nojs} 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:
+@table @code
+@item 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}.
+
+@item 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}.
+
+@end table