api-reference.texi (5817B)
1 @node Reference 2 @chapter Reference 3 4 @menu 5 * Headers for HTTP 402:: Headers for the 402 status code and their effect on the user agent's operation 6 * JavaScript API:: JavaScript API to communicate with the wallet 7 * Stylesheet-based presence detection:: Presence detection using CSS style sheets and no JavaScript 8 @end menu 9 10 @node Headers for HTTP 402 11 @section Headers for HTTP 402 12 13 The HTTP status code @code{402 Payment Required} can be used by the merchant 14 frontend to trigger operations related to payments in the user agent. There 15 are three different types of possible interactions: 16 17 @menu 18 * Payment:: Payment 19 * Refund:: Refund 20 * Tipping:: Tipping 21 @end menu 22 23 @node Payment 24 @subsection Payment 25 @cindex payment 26 27 For payments, the user agent associates at most one proposal with every URL via the 28 proposal's @code{fulfillment_url} field. The associated proposal is 29 either missing (in case it does not exist), paid (in case the payment 30 for it was successfully sent to the merchant) or unpaid. If the 31 associated proposal is unpaid, @code{402 Payment Required} will cause 32 the user agent to pay for the associated proposal. 33 34 The following headers for @code{402 Payment Required} are involved in 35 processing payments: 36 37 @table @code 38 @item X-Taler-Contract-Url 39 If there is no associated proposal, the user agent will fetch a proposal from 40 this URL and process it. This typically prompts the user to agree to pay. 41 42 @item X-Taler-Offer-Url 43 If there is no associated proposal and @code{X-Taler-Contract-Url} is not 44 specified, the browser will navigate to this URL. 45 @end table 46 47 48 @node Refund 49 @subsection Refund 50 @cindex refund 51 52 A merchant can give a customer a refund, for example if they are unable 53 to deliver the goods or if the goods turned out to be defective. Refunds 54 can only be issued before the exchange has transferred the funds to the 55 customer as per the @code{refund_deadline} of the contract. 56 @cindex refund deadline 57 58 The following headers for @code{402 Payment Required} are involved in 59 processing refunds: 60 61 @table @code 62 @item X-Taler-Refund-Url 63 If this header present, the value of this header must be a URL that the user agent can use to request and process refunds. 64 @end table 65 66 67 @node Tipping 68 @subsection Tipping 69 @cindex tipping 70 71 The following headers for @code{402 Payment Required} are involved in 72 tipping clients: 73 74 @table @code 75 @item X-Taler-Tipping-Url 76 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-Tipping-Exchange} and @code{X-Taler-Tipping-Amount} must also be present. The wallet will then generate appropriate planchets and POST the required information in JSON to this URL. The merchant should add the @code{tip_id} and @code{instance} fields and pass the POSTed @code{planchets} to its backend at the @code{/tip-pickup} URI. The wallet will expect a response in the same format as returned by the backend. Note that the tipping URL will typically need to encode the @code{tip_id} returned by the @code{/tip-authorize} function of the merchant's backend. 77 78 @item X-Taler-Tipping-Exchange 79 Exchange base URL for the exchange that the merchant will allow the client to withdraw the tip from. 80 81 @item X-Taler-Tipping-Amount 82 Amount of tip that the user is receiving, in the standard amount format (CURR:X.Y). 83 84 @item X-Taler-Tipping-Deadline 85 Optional deadline (in the usual HTTP ``Date'' format) until which the tip is available. Later requests may be rejected by the merchant. Note that the absence of this field should not be understood to imply that the offer is valid indefinitely. However, if there is a deadline, the wallet may visually indicate to the user that the tip needs to be picked up in a timely fashion (assuming the wallet interactively asks for confirmation and the deadline is near). 86 87 @end table 88 89 90 91 @node JavaScript API 92 @section JavaScript API 93 94 The following functions are defined in the @code{taler} namespace of the @code{taler-wallet-lib} helper library 95 available at @url{https://git.taler.net/web-common.git/tree/taler-wallet-lib.js}. 96 97 @table @code 98 @item onPresent(callback: () => void) 99 Add a callback to be called when support for Taler payments is detected. 100 101 @item onAbsent(callback: () => void) 102 Add a callback to be called when support for Taler payments is disabled. 103 104 @item pay(@{contract_url: string, offer_url: string@}) 105 Results in the same action as a @code{402 Payment Required} with @code{contract_url} in 106 the @code{X-Taler-Contract-Url} header and @code{offer_url} in the @code{X-Taler-Payment-Url} header. 107 108 @item refund(refund_url: string) 109 Results in the same action as a @code{402 Payment Required} with @code{refund_url} in 110 the @code{X-Taler-Refund-Url} header. 111 112 @end table 113 114 @node Stylesheet-based presence detection 115 @section Stylesheet-based presence detection 116 117 Stylesheet-based presence detection will be applied on all pages that have the 118 @code{data-taler-nojs} attribute of the @code{html} element set @code{true}. 119 The default/fallback stylesheet, that will be taken over by the wallet once 120 installed, must be included with the id @code{taler-presence-stylesheet}, like 121 this: 122 123 The following CSS classes can be used: 124 @table @code 125 @item taler-installed-hide 126 A CSS rule will set the @code{display} property for this class to @code{none} once the Taler wallet is installed and enabled. 127 If the wallet is not installed, @code{display} will be @code{inherit}. 128 129 @item taler-installed-show 130 A CSS rule will set the @code{display} property for this class to @code{inherit} once the Taler wallet is installed and enabled. 131 If the wallet is not installed, @code{display} will be @code{none}. 132 133 @end table