commit 0e4795c27cade8b906133327955e5edcc8aaad56
parent f8c0df8630e2c54f302d988280a666bb703a138f
Author: Marcello Stanisci <marcello.stanisci@inria.fr>
Date: Wed, 16 Nov 2016 22:37:51 +0100
including track-transfer code sample
Diffstat:
1 file changed, 48 insertions(+), 14 deletions(-)
diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
@@ -162,7 +162,7 @@ to the frontend @code{/donate} URL. For this, the HTML would be as
follows:
@smallexample
-@include ../index.php
+@verbatiminclude ../index.php
@end smallexample
When the server-side handler for @code{/donate} receives the form submission,
@@ -177,7 +177,7 @@ A minimalistic @code{donate.php} implementation is shown below (in PHP):
@smallexample
// php/donate.php
-@include ../donate.php
+@verbatiminclude ../donate.php
@end smallexample
Given this response, the Taler wallet will fetch the contract from
@@ -207,7 +207,7 @@ A simple @code{/generate-contract.php} handler may thus look like this:
@smallexample
// php/generate-contract.php
-@include ../generate-contract.php
+@verbatiminclude ../generate-contract.php
@end smallexample
Note that in practice the frontend might want to generate a monotonically
@@ -218,7 +218,7 @@ The function @code{post_to_backend} is shown below; we will use it
again in other examples:
@smallexample
-@include ../backend.php
+@verbatiminclude ../backend.php
@end smallexample
The function @code{build_error} is shown below, it returns JSON data
@@ -227,7 +227,7 @@ see @code{http://api.taler.net/api-common.html#errordetail}.
@smallexample
@c FIXME, build_error() doesn't respect error-reporting format yet!
-@include ../error.php
+@verbatiminclude ../error.php
@end smallexample
After the browser has fetched the contract, the user will
@@ -248,7 +248,7 @@ The following code implements this in PHP:
@smallexample
// php/pay.php
-@include ../pay.php
+@verbatiminclude ../pay.php
@end smallexample
Do not be confused by the @code{isset} test for the session state. In
@@ -281,7 +281,7 @@ transaction_id=<TRANSACTION_ID>×tamp=<CONTRACTTIMESTAMP>
@smallexample
// php/fulfillment.php
-@include ../fulfillment.php
+@verbatiminclude ../fulfillment.php
@end smallexample
@node Back-office-integration
@@ -302,22 +302,56 @@ To that regard, the frontend's main task are:
@end itemize
We implement the first point with a simple HTML form. For simplicity, we
-keep one page for gathering input data for both tracking directions. See
-in the code sample below:
+have one single page for gathering input data for both tracking directions.
+See below the code sample:
@smallexample
// php/track-input.php
-@include ../track-input.php
+@verbatiminclude ../track-input.php
@end smallexample
The @code{track-transaction.php} script is now responsible for taking the
-Taler transaction ID given by the user in the @code{tid} field, and issuing
-a @code{/track/transaction} REST call to the backend, see
-@code{http://api.taler.net/api-merchant.html#get--track-transaction}.
+Taler transaction ID given by the user in the @code{tid} field, and using it
+to issue a @code{/track/transaction} REST call to the backend,
+see @code{http://api.taler.net/api-merchant.html#get--track-transaction}. Note that the backend will then request this information
+from the exchange. The reason why we do this extra step through
+the backend is that the frontend is not supposed to perform any
+cryptographic work, and so it relies on the backend for that.
@smallexample
// php/track-transaction.php
-@include ../track-transaction.php
+@verbatiminclude ../track-transaction.php
+@end smallexample
+
+If the backend returned an HTTP status code @code{202}, then the
+exchange did not perform the wire transfer for timing reasons,
+but no errors occurred. We tell the user when to retry this
+operation.
+
+In the @code{foreach} loop, we construct the list of all the
+wire transfers which paid back transaction @code{tid}. For
+simplicity, the list will report only two values: the wire transfer
+identifier and the date when the transfer occurred. Nonetheless,
+the data returned by the backend contains more information that
+can be shown to the user.
+
+As of @code{track-transfer.php}, see below the code sample, we
+first check if the user
+submitted all the parameters, and then we forward the request to
+the backend, that in turn will request this information from the
+exchange.
+@c FIXME /show/refer to/ get_to_backend()
+Note the case when HTTP status code @code{402} is returned: due to
+extra checks that the backend does against the data returned by the
+exchange, the backend detected some inconsistency in the exchange's
+response. Accordingly, we report this situation to the user, who
+should now report this situation to the backend and exchange administrators.
+If instead everything went fine, we first output how much @code{wtid} was
+worth and when it has been performed, and finally in the @code{foreach}
+loop we construct the list of the transaction IDs paid back by @code{wtid}.
+
+@smallexample
+@verbatiminclude ../track-transfer.php
@end smallexample
@bye
