From e96e2fdf5e2dae3b748869f42a0298dba0e7b06a Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 23 Mar 2016 15:08:51 +0100 Subject: commenting out old blog spec; adding /public-accounts/details API --- example-essay-store.rst | 112 +++++++++++++++++++++++++++--------------------- 1 file changed, 63 insertions(+), 49 deletions(-) (limited to 'example-essay-store.rst') diff --git a/example-essay-store.rst b/example-essay-store.rst index 68079a20..a93d5d6c 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -16,57 +16,70 @@ 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: +.. + 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. -* `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. +.. + Describing implementation of the above scenario +-------------- +Before reading +-------------- +To properly understand this example, the read should be familiar with Taler's terminology; +in particular, definitions like `contract`, `fulfillment URL` and `offering URL` are assumed +to be known. Refer to :ref:`contract` and :ref:`payprot` in order to get some general insight +on terms and interactions between components. -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. -.. - Describing implementation of the above scenario +This section describes how the demonstrator essay store interacts with the Taler system. +This demonstrator lies in `examples/blog` of `git://taler.net/merchant/examples/blog` The essay store, available at https://blog.demo.taler.net, is such that its homepage -is a list of buyable articles and each list item is a reference to an `offering +is a list of buyable articles and each article is a reference to an `offering URL` (see :ref:`offer`). In particular, this offering URL has the following format: `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId` @@ -94,11 +107,12 @@ Once the user visits the offering URL by clicking on some article's title, the m 3. returns a page which can detect if a Taler wallet is installed in the user's browser and, if so, automatically downloads the contract from the merchant; if not, displays a paywall for credit card payment. Note that the contract's request is entirely managed by the page's - JavaScript and not by the wallet (FIXME explain reason). The wallet gets involved once the - contract arrives and the JavaScript fires a `taler-confirmation-event` containing the contract, - see point 1. of :ref:`offer`. + JavaScript and not by the wallet; that gives more flexibility to the merchants by reducing + the communication between wallets and shops. The wallet gets involved once the + contract arrives and the JavaScript fires a `taler-confirm-contract` event containing the + contract, see point 1. of :ref:`offer`. -4. the wallet then visits the fulfillment URL associated with this purchase (the fulfillment +4. the wallet visits the fulfillment URL associated with this purchase (the fulfillment URL's path is indicated in the contract, so the wallet has to just add `tid` and `timestamp` to it). -- cgit v1.2.3