From eec9bc2e4c4f5c6ee751f6c924be255e6c0ca433 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Sun, 4 Jun 2017 17:30:03 +0200 Subject: copy reference section into PHP manual as well --- php/doc/tutorial.texi | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) (limited to 'php') diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi index 165c6a3..7b8d31b 100644 --- a/php/doc/tutorial.texi +++ b/php/doc/tutorial.texi @@ -57,6 +57,7 @@ Texts. A copy of the license is included in the section entitled * Hello-world:: 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 @@ -1003,6 +1004,88 @@ Rationale: Joining non-canonical URLs with relative URLs (e.g. "exchange.exampl results in different and slightly unexpected behavior in some URL handling libraries. Canonical URLs give more predictable results with standard URL joining. + +@c The following section is copied from the Python manual, +@c changes should be done there and then copied back here. +@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. + +@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 + + @c ********************************************************** @c ******************* Appendices ************************* @c ********************************************************** -- cgit v1.2.3