contract -> order

2 files changed, 36 insertions, 27 deletions

diff --git a/php/contract.php b/php/contract.php
index ec75fb7..7582ae7 100644
--- a/php/contract.php
+++ b/php/contract.php
@@ -4,7 +4,7 @@
   include_once 'config.php';
   include_once 'helpers.php';
 
-  function make_contract($transaction_id, $now){
+  function make_order($transaction_id, $now){
     $contract
       = array(
         'amount' =>
diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
index 78aa4a0..70fd52c 100644
--- a/php/doc/tutorial.texi
+++ b/php/doc/tutorial.texi
@@ -94,7 +94,7 @@ Taler with Web shops. It describes how to create a Web shop that
 processes payments with the help of a GNU Taler merchant
 @emph{backend}.  In the second chapter, you will learn how to trigger
 the payment process from the Web site, how to communicate with the
-backend, how to generate a contract and process the payment.  The
+backend, how to generate a order and process the payment.  The
 third chapter covers the integration of a back office with the
 backend, which includes tracking payments for orders, matching
 payments to orders, and persisting and retrieving contracts.
@@ -157,7 +157,7 @@ account information are encapsulated within the Taler backend.
 This section describes how to setup a simple shop, which exposes a
 button to get donations via Taler. The expected behaviour is that once
 the ``donate'' button is clicked, the customer will receive a Taler
-contract offering him the opportunity to make a fixed donation,
+*proposal* offering him the opportunity to make a fixed donation,
 for example to donate 1 KUDOS to the charity operating the shop.
 
 All the code samples shown below in the tutorial can be found at
@@ -232,7 +232,7 @@ it will return a HTML page that will take care of:
 
 @itemize
 @item showing a credit card paywall to the user if no wallet is found, and
-@item fetching a Taler contract and passing it to the wallet if one is found
+@item fetching a Taler proposal and passing it to the wallet if one is found
 @end itemize
 
 A minimalistic @code{donate.php} implementation is shown below (in PHP):
@@ -245,23 +245,34 @@ A minimalistic @code{donate.php} implementation is shown below (in PHP):
 @verbatiminclude ../donate.php
 @end smallexample
 
-Given this response, the Taler wallet will fetch the contract from
+Given this response, the Taler wallet will fetch the proposal from
 @url{/generate-contract.php} and display it to the user.
 
 If the wallet is not present, the HTML body will be shown and the
 Taler headers and the 402 status code ought to be ignored by the
 browser.
 
-@section A helper function to generate the proposed contract
+@section A helper function to generate the order
 
-We first define a helper function @code{make_contract} that will
-generate a complete Taler contract as a nested PHP array.  The
-function takes only the transaction ID and the timestamp as arguments;
-all of the other details of the contract are hardcoded in this simple
+We make distinction between *three* different stages of the
+document that describes the purchase being served.
+
+In a very first stage, we call it the @emph{order}: that occurs when
+the frontend generates the first JSON that misses some information
+that the backend is supposed to add.  When the backend completes the
+order and signs it, we have a @emph{proposal}.  The proposal is what
+the user is prompted with, and allows them to confirm the purchase.
+Once the user confirms the purchase, the wallet makes a signature over
+the proposal, turning it into a @emph{contract}.
+
+We first define a helper function @code{make_order} that will
+generate a complete Taler order as a nested PHP array.  The
+function takes only the order ID and the timestamp as arguments;
+all of the other details of the order are hardcoded in this simple
 example.
 
-The following code generate a contract proposal about donating 1 KUDOS
-to the 'Taler charity program':
+The following code generate a order about donating 1 KUDOS to the
+'Taler charity program':
 
 @cindex contract
 @smallexample
@@ -273,8 +284,8 @@ to the 'Taler charity program':
 @section Signing and returning the proposal
 
 The server-side handler for @code{/generate-contract.php} has to call
-@code{make_contract} and then POST the result to the backend at
-@code{/contract}.  By POSTing the proposed contract to the backend we get a
+@code{make_order} and then POST the result to the backend at
+@code{/proposal}.  By POSTing the order to the backend we get a
 cryptographic signature over its contents.  The result is then
 returned to the wallet.
 
@@ -282,7 +293,7 @@ A simple @code{/generate-contract.php} handler may thus look like this:
 
 @cindex signature
 @cindex backend
-@cindex contract
+@cindex order
 @smallexample
 // php/generate-contract.php
 @verbatiminclude ../generate-contract.php
@@ -290,8 +301,8 @@ A simple @code{/generate-contract.php} handler may thus look like this:
 
 @c FIXME: improve example to do this right?
 Note that in practice the frontend might want to generate a monotonically
-increasing series of transaction IDs to avoid a chance of collisions.
-Transaction IDs must be in the range of @math{[0:2^{51})}.
+increasing series of order IDs to avoid a chance of collisions.
+Order IDs must be in the range of @math{[0:2^{51})}.
 
 @section Handling errors
 
@@ -314,10 +325,10 @@ see @code{http://api.taler.net/api-common.html#errordetail}:
 @section Initiating the payment process
 
 @cindex fulfillment URL
-After the browser has fetched the contract proposal, the user will be
+After the browser has fetched the proposal, the user will be
 given the opportunity to affirm the payment.  Assuming the user
 affirms, the browser will navigate to the ``fulfillment_url'' that
-was specified in the contract.
+was specified in the proposal.
 
 The fulfillment page can be called by users that have already paid for
 the item, as well as by users that have not yet paid at all.  The
@@ -325,14 +336,14 @@ fulfillment page must thus use the HTTP session state to detect if the
 payment has been performed already, and if not request payment from
 the wallet.
 
-For our example, we include in the URI of the fulfillment page the information
-which is needed to allow the page to determine which contract the user is
-trying to access.
+For our example, we include in the URI of the fulfillment page the
+information which is needed to allow the page to determine which
+contract the user is trying to access.
 Thus, the fulfillment URL for our example looks like the following:@*
 
 @smallexample
 https://shop.com/fulfillment.php? \
-transaction_id=<TRANSACTION_ID>&timestamp=<CONTRACTTIMESTAMP>
+order_id=<ORDER_ID>&timestamp=<ORDERTIMESTAMP>
 @end smallexample
 
 The fulfillment handler at @code{/fulfillment.php}
@@ -352,10 +363,8 @@ headers:
 
 @table @code
 @item X-Taler-Contract-Hash
-@cindex X-Taler-Contract-Hash
-The wallet needs to know which contract we are asking it to pay for.
-To reduce bandwidth consumption, we do not transmit the full contract
-again, but just the hash of it.
+@cindex X-Taler-Contract-Url
+FIXME
 @item X-Taler-Pay-Url
 @cindex X-Taler-Pay-Url
 This URL specifies where we expect the wallet to send the payment.