This file is part of GNU TALER.
Copyright (C) 2014, 2015, 2016 INRIA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2.1, or (at your option) any later version.
TALER is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
@author Florian Dold
Example: Essay Store
The main page of the essay store shows links to essays of the form `/essay?name=:name`.
The `/essay` URL takes the following query parameters:
* `name`: mandatory, name of the essay
* `tid`: optional, transaction ID generated by the merchant for the
contract that was used to purchase an instance of the article
* `timestamp`, optional, timestamp for the contract that was used to purchase
the essay with the given `tid`.
These are the steps for showing `/essay`. If the wallet is not present in
steps 2 and 3, the user agent is redirected to a mock credit card
1. The server checks the status of the the essay with the name `name` in the server-side
* If the essay is marked as payed, display the essay.
* Otherwise proceed with step 2
2. The server checks if the `tid` and `timestamp` query parameters are present
* If `tid` and `timestamp` are present, restore the contract for the essay
(using `tid` as transaction id in the contract, `timestamp` as timestamp
and `timestamp+REFUND_DELTA` as refund deadline) and emit the
`taler-execute-contract` DOM event in the user agent.
* Otherwise proceed with step 3
3. The server generates a new contract and emits the `taler-confirm-contract` DOM event in the user agent,
with the essay name as repurchase correlation identifier and `/essay?name=:name?tid=:tid` as fulfillment url.
In step 2, the `taler-execute-contract` event has the following parameters:
* `H_contract`: hash of the contract that was restored
* `payment_url`: The internal URL `/pay?H_contract=...` of the essay store,
will set the server-side session state for the article associated with the
contract hash on successful coin deposit. The contract hash is associated
with the article name in the server-side session state when the contract is restored.
* `offer_url`: Link to a teaser page (`/teaser?name=...`), which also contains a link to the article
page, without the `tid` parameter.
Note that we assume that all essays cost the same (otherwise the amount would have to be included in
the restoration information in the /essay fulfillment URL). The refund deadline is computed
by adding the merchant-specific constant `REFUND_DELTA` to the contract's timestamp.