summaryrefslogtreecommitdiff
path: root/example-essay-store.rst
blob: 2271fa3953bc8ffc83f16bc8df43e1395fb1881d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
..
  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
payment page.

1. The server checks the status of the the essay with the name `name` in the server-side
   session state

  * 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.