summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--api-bank.rst9
-rw-r--r--example-essay-store.rst112
-rw-r--r--integration-merchant.rst1
3 files changed, 73 insertions, 49 deletions
diff --git a/api-bank.rst b/api-bank.rst
index a78429bd..0f88088b 100644
--- a/api-bank.rst
+++ b/api-bank.rst
@@ -71,3 +71,12 @@ the recipient's account
reason: string
}
+
+--------
+Util API
+--------
+
+Whenever the user wants to know the bank account number of a public account,
+the following path returns a human readable HTML containing this information
+
+ `/public-accounts/details?account=accountName`
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).
diff --git a/integration-merchant.rst b/integration-merchant.rst
index 093204d2..e1a563fa 100644
--- a/integration-merchant.rst
+++ b/integration-merchant.rst
@@ -16,6 +16,7 @@
Interaction with merchant websites
==================================
+.. _payprot:
++++++++++++++++
Payment protocol