commit ec415c652d9597e0cace0a251297a8feece7db5d
parent 9319c5693ac2017b3d713c76810c4b0eb16ccf23
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 19 Nov 2016 19:55:32 +0100
fix english
Diffstat:
| M | php/doc/tutorial.texi | | | 115 | ++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------- |
1 file changed, 76 insertions(+), 39 deletions(-)
diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
@@ -401,73 +401,110 @@ anything goes wrong, the wallet will handle the respective error.
@chapter Integration with the back office
This chapter shows how to implement the back office Web interface.
-Namely, we want to verify if we received a wire transfer in
-relation to a given Taler transaction. We are also interested in the
-opposite direction: which Taler transactions are related to a
-given wire transfer.
-@c FIXME: does the reader know so far that a Taler transaction
-@c is meant to trigger a wire transfer?
-To that regard, the frontend's main task are:
+
+We will use the term @emph{transaction} to refer to the business
+transaction that a merchant has with a customer (and the related
+communication with the Taler exchange for payment), and the term
+@emph{wire transfer} to refer to the exchange settling its accounts
+with the merchant.
+
+Given that Taler deals with microtransactions, not every customer
+payment processed with Taler will necessarily correspond to a wire
+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.
+
+In this chapter, we will see how a merchant can obtain the
+mapping from transactions to wire transfers and vice versa.
+Additionally, we will describe how to obtain a list of all
+transactions known to the backend.
+
+@section Entry page
+
+Given this charge, the back office's main tasks are:
@itemize
-@item gather the input from the user and forward it to the backend
-@item transform the backend response in HTML and return it to the user
+@item Allow the back office operator to specify a transaction ID, and display the corresponding
+ wire transfer identifiers
+@item Allow the back office operator to specify a wire transfer ID, and display all of
+ the corresponding transaction IDs
+@item Allow the back office operator to obtain a list of all transactions.
@end itemize
-We implement the first point with a simple HTML form. For simplicity, we
-have one single page for gathering input data for both tracking directions.
-See below the simple HTML entry page for the back office:
+We implement these with a simple HTML form. For simplicity, we have
+one single page for gathering input data for both tracking directions:
@smallexample
// php/track-input.html
@verbatiminclude ../track-input.html
@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 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.
+@c TODO: expand with button to obtain list of all transactions.
+
+
+@section Tracking a transaction
+
+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 using it to issue a @code{/track/transaction} request to the
+backend, see
+@url{http://api.taler.net/api-merchant.html#get--track-transaction}.
+Note that the backend may then request this information from the
+exchange, or retrieve it from its own cache if it has already obtained
+it. The backend will also check signatures from the exchange, persist
+the information obtained, and complain if the exchange ever changes
+its facts in an inconsistent manner.
@smallexample
// php/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.
+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.
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. Note that the function @code{get_to_backend}
-is shown in the previous chapter.
-
-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.
-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}.
+can be shown to the user.
+
+@section Tracking a wire transfer
+
+To track a wire transfer, we first check if the user submitted all the
+required parameters, and then we forward the request to the backend.
+Again, the backend may request missing information from the exchange,
+verify signatures, persist the result and complain if there are
+inconsistencies.
+
+In the case that the backend detects inconsistencies, an HTTP status
+code of @code{402} is returned. In this case, we report this
+situation to the user, who should now report this situation to the
+exchange's auditors as the exchange is misbehaving.
+
+In the usual case where everything went fine, we first output the
+amount that was supposed to have been transfered under the given
+@code{wtid}, and when it was performed (according to the exchange).
+Finally, in the @code{foreach} loop, we construct the list of the
+transaction IDs paid by the wire transfer:
@smallexample
@verbatiminclude ../track-transfer.php
@end smallexample
+@section Listing all transactions
+
+FIXME.
+
+
@node Advanced topics
@chapter Advanced topics
