commit c17064ee27a806b570dad1f18bd8f870e67a8584
parent d2bf2ef05d42bf02422890e6f0a247c2e5303b79
Author: Marcello Stanisci <marcello.stanisci@inria.fr>
Date: Tue, 6 Dec 2016 18:39:26 +0100
Describing the JS way, 80%
Diffstat:
2 files changed, 45 insertions(+), 46 deletions(-)
diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
@@ -373,13 +373,13 @@ wallet where to go to retrieve the original offer.
The final next step for the frontend is to accept the payment from the
wallet. For this, the frontend must implement a payment handler at
-the URI specified for as the @code{X-Taler-Pay-Url} in the headers
-as explained above.
+the URI specified in the @code{X-Taler-Pay-Url} header, as explained
+above.
-The role of the @code{/pay} handler is to receive the payment from
-the wallet and forward it to the backend. If the backend reports
-that the payment was successful, the handler needs to update the
-session state with the browser to remember that the user paid.
+The role of the @code{/pay.php} handler is to receive the payment
+from the wallet and forward it to the backend. If the backend
+reports that the payment was successful, the handler needs to update
+the session state with the browser to remember that the user paid.
The following code implements this in PHP:
@@ -415,7 +415,7 @@ transfer. The Taler exchange may aggregate multiple payments from
transactions into one larger wire transfer. The @var{refund_deadline}
and the @var{pay_deadline} values in the contract specify the
timeframes within which the exchange is permitted to perform such
-aggregations.
+aggregations, see @ref{Taler contracts}.
In this chapter, we will see how a merchant can obtain the
mapping from transactions to wire transfers and vice versa.
@@ -467,11 +467,10 @@ its facts in an inconsistent manner.
@end smallexample
If the backend returned an HTTP status code @code{202} (Accepted),
-this means that the exchange simply did yet not perform the wire
-transfer. This is usually the case before the @var{refund_deadline} as
-the exchange is waiting for additional opportunities to aggregate
-transactions. In this case, we tell the user when to retry this
-operation later.
+this means that the exchange simply did not yet perform the wire
+transfer. This is usually the case before @var{pay_deadline} as the exchange
+is waiting for additional opportunities to aggregate transactions.
+In this case, we tell the user when to retry this operation later.
In the @code{foreach} loop, we construct the list of all the
wire transfers which paid back transaction @code{tid}. For
@@ -516,12 +515,12 @@ Our example frontend, implements this feature by orchestrating two
parts:
@itemize
-@item The @code{history.php?days=<DAYSAGO>} script, whose @code{days}
+@item The @code{/history.php?days=<DAYSAGO>} script, whose @code{days}
parameter indicates how old the oldest returned transaction should
be in terms of days. The script will then translate @emph{<DAYSAGO>}
in a timestamp, and issue the call to backend's
@code{/history?date=<TIMESTAMP>}. The data it receives from the
- backend is finally returned in JSON format to the caller.
+ backend is finally returned in JSON format to the browser.
@item A JavaScript function, imported within @code{backoffice.html},
that issues the HTTP GET to @code{/history.php?days=<DAYSAGO>}
@@ -591,15 +590,15 @@ attribute in order to make it work with your Web site.
The detection works by @code{taler-fallback.css} hiding any tag from the
@code{taler-installed-show} class, in case no wallet is installed. If otherwise
-the wallet is installed, the wallet takes action by hiding any tag from
-@code{taler-installed-hide} and overriding @code{taler-fallback.css} logic
+the wallet is installed, the wallet takes action by hiding any tag from the
+@code{taler-installed-hide} class and overriding @code{taler-fallback.css} logic
by showing any tag from the @code{taler-installed-show} class.
@subsection The JavaScript way
-In this case, the @code{taler-wallet-lib} 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:
+@code{taler-wallet-lib.js} 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:
@smallexample
<html lang="en">
@@ -731,8 +730,9 @@ 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. The
-information is also likely to be used by tax audits of the merchant.
+intends to pay, and can be used by the customer as a receipt.
+@c FIXME: a receipt not including the item's price?
+The information is also likely to be used by tax audits of the merchant.
@item delivery_date
Time by which the product is to be delivered to the
@var{delivery_location}.
@@ -789,8 +789,10 @@ ZIP code for delivery, as found on a postal package.
Street name for delivery, as found on a postal package.
@item street number
Street number (number of the house) for delivery, as found on a postal package.
-@item name
+@item name receiver name for delivery, either business or person name.
+
@end 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
@@ -798,7 +800,6 @@ that they do not understand as a key-value list.
@end table
-
@node Inline contracts
@section Inlining contracts in HTTP headers
@cindex optimization
@@ -820,34 +821,32 @@ which implements inline contracts.
The wallet will then look for the @code{X-Taler-Contract} header, and fetch the
inlined contract if this header is found. Please note that this feature is not
-yet implemented.
+yet implemented in the wallet.
@node Payments using JavaScript
@section Triggering payments using JavaScript
@cindex JavaScript
+
+@subsection Offering contracts
+FIXME/TODO
+
+@subsection Receiving payments
@cindex payment
-In the example in section @ref{Initiating the payment process},
-we used a GET request to trigger the payment. This section describes how we
-could have instead performed the interaction with the wallet directly from the
-button via JavaScript.
+In the example in section @ref{Initiating the payment process}, the fulfillment
+handler @code{/fulfillment.php} triggers the payment in the wallet by returing
+the three needed values (contract hashcode, pay URL, offer URL) via HTTP headers.
-The function @code{executePayment} exported by @code{taler-wallet-lib.js} will basically
-hand its three parameters to the wallet which implements the following semantics:@*
-check in the internal DB if @code{$response['H_contract']} has an entry, and:
-@itemize
-@item if that is the case, then the user accepted the contract previously and the wallet
-sends a deposit permission @footnote{Roughly speaking, a deposit permission is a JSON
-containing the coins to pay for a contract. Its full specification is available at:
-@url{https://api.taler.net/api-merchant.html#depositpermission}} to @code{/frontend-pay}.
-If this operation succeeds, then visit again the fulfillment URL, and finally enjoy
-the product.
-@item if not, redirect the browser to @code{/donate.php} (which will then reinitiate the
-whole contract negotiation). This happens when the user visits a shared fulfillment URL.
-The idea is to let that user buy the same products as the user who shared the fulfillment
-URL. Nonetheless, the shop is not forced to follow this semantics when provides the third
-parameter to @code{executePayment}.
-@end itemize
+The same action can be accomplished *with* JavaScript, thanks to @code{taler-wallet-lib.js}
+of @emph{web-common} repository.
+The fulfillment handler needs just to call the function @code{executePayment} feeding it
+with the needed three parameters. The wallet will then get triggered and proceed with the
+payment. See below a full example:
+
+@smallexample
+// ../fulfillment-js.php
+@verbatiminclude ../fulfillment-js.php
+@end smallexample
@node The Fulfillment page
diff --git a/php/inline.php b/php/inline.php
@@ -15,8 +15,8 @@
$response['status_code']);
}
- http_response_code(402);
- header (sprintf('X-Taler-Contract: %s', $ret));
+ http_response_code(402); // Payment required
+ header ("X-Taler-Contract: $ret"); // Inline contract
?>
<!DOCTYPE html>
<html lang="en">
