From ae90c24fb77d37e02fcfaf0ee9ef64c8b72bb1c1 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Mon, 20 Jun 2016 16:53:09 +0200 Subject: addressing #4575 --- Makefile | 2 ++ favicon.ico | Bin 0 -> 1150 bytes robots.txt | 20 ++++++++++++++++++++ 3 files changed, 22 insertions(+) create mode 100644 favicon.ico create mode 100644 robots.txt diff --git a/Makefile b/Makefile index f09f2a04..51af85c5 100644 --- a/Makefile +++ b/Makefile @@ -53,6 +53,8 @@ clean: # remove all cached state first. html: $(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html + @cp favicon.ico $(BUILDDIR)/html + @cp robots.txt $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 00000000..141b93d3 Binary files /dev/null and b/favicon.ico differ diff --git a/robots.txt b/robots.txt new file mode 100644 index 00000000..0a639917 --- /dev/null +++ b/robots.txt @@ -0,0 +1,20 @@ +# +# robots.txt +# +# This file is to prevent the crawling and indexing of certain parts +# of your site by web crawlers and spiders run by sites like Yahoo! +# and Google. By telling these "robots" where not to go on your site, +# you save bandwidth and server resources. +# +# This file will be ignored unless it is at the root of your host: +# Used: http://example.com/robots.txt +# Ignored: http://example.com/site/robots.txt +# +# For more information about the robots.txt standard, see: +# http://www.robotstxt.org/robotstxt.html +# +# For syntax checking, see: +# http://www.frobee.com/robots-txt-check + +User-agent: * +Crawl-delay: 10 -- cgit v1.2.3 From 0c8a2b29e26e364fa7048b3607f234cf66f04b37 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Mon, 20 Jun 2016 17:10:28 +0200 Subject: fixing TABs in Makefile --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 51af85c5..48c5c118 100644 --- a/Makefile +++ b/Makefile @@ -53,8 +53,8 @@ clean: # remove all cached state first. html: $(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html - @cp favicon.ico $(BUILDDIR)/html - @cp robots.txt $(BUILDDIR)/html + @cp favicon.ico $(BUILDDIR)/html + @cp robots.txt $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -- cgit v1.2.3 From bba5907f359908d0cb01ef48a7f994eeb93ce081 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Mon, 20 Jun 2016 18:18:24 +0200 Subject: using /var/www/favicon_robots in "api" --- Makefile | 2 -- favicon.ico | Bin 1150 -> 0 bytes robots.txt | 20 -------------------- 3 files changed, 22 deletions(-) delete mode 100644 favicon.ico delete mode 100644 robots.txt diff --git a/Makefile b/Makefile index 48c5c118..f09f2a04 100644 --- a/Makefile +++ b/Makefile @@ -53,8 +53,6 @@ clean: # remove all cached state first. html: $(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html - @cp favicon.ico $(BUILDDIR)/html - @cp robots.txt $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/favicon.ico b/favicon.ico deleted file mode 100644 index 141b93d3..00000000 Binary files a/favicon.ico and /dev/null differ diff --git a/robots.txt b/robots.txt deleted file mode 100644 index 0a639917..00000000 --- a/robots.txt +++ /dev/null @@ -1,20 +0,0 @@ -# -# robots.txt -# -# This file is to prevent the crawling and indexing of certain parts -# of your site by web crawlers and spiders run by sites like Yahoo! -# and Google. By telling these "robots" where not to go on your site, -# you save bandwidth and server resources. -# -# This file will be ignored unless it is at the root of your host: -# Used: http://example.com/robots.txt -# Ignored: http://example.com/site/robots.txt -# -# For more information about the robots.txt standard, see: -# http://www.robotstxt.org/robotstxt.html -# -# For syntax checking, see: -# http://www.frobee.com/robots-txt-check - -User-agent: * -Crawl-delay: 10 -- cgit v1.2.3 From 36c085b4766cb4ca84da4c65c5cd8e0c16046961 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 6 Jul 2016 17:47:16 +0200 Subject: simplifying payment protocol description --- integration-merchant.rst | 148 +++++++++++++++-------------------------------- 1 file changed, 47 insertions(+), 101 deletions(-) diff --git a/integration-merchant.rst b/integration-merchant.rst index 76a9ae5a..999fe411 100644 --- a/integration-merchant.rst +++ b/integration-merchant.rst @@ -18,115 +18,61 @@ Interaction with merchant websites .. _payprot: -++++++++++++++++ -Payment protocol -++++++++++++++++ - -The events described below get triggered when the user confirms its -purchase on a checkout page, or visits some merchant's resource -that needs a payment to be visualized. We call this situation `IIG` (Interest -In some Good). The user can initialize a IIG by visiting one of the following kind -of URL - -* offering URL -* fulfillment URL - -Offering URLs are visited the very first time the user wants to get some resource, whereas -fulfillment URLs let both the user access bought items later in the future (by bookmarking it) -and share its purchases with other users. In the last case, the fulfillment URL acts like -a `pointer to the chart` whose items can be bought by who visits the fulfillment URL. - -There is no hard separation between physical and virtual resources since -the receipt for a physical resource plays the same role of a 100% virtual resource like a -blog article. In other words, when seeing a pay-per-view blog article on his screen, then -the user has payed for the article; on the other end, when seeing an electronic receipt of -a physical good on his screen, the user will receive it by mail. - -IIG triggers different flows according to the user visiting an offering or a fulfillment -URL. For clarity, below are listed the steps taken when the user visits an offering URL. - -.. _byoffer: - ---------------------- -IIG by `offering` URL ---------------------- - -0. If the state associated to the resource requested is `payed`, go to 7. - -1. The merchant sends the following object embedded in a `taler-confirm-contract` event ++++++++++++++++++++ +The payment process ++++++++++++++++++++ + +Before delving into the technical details, it is worth surveying the payment process from an +abstract point of view. By design, Taler implements the following three points: + +0. The user must accept a contract before paying for something +1. The bought item(s) must be made available again in the future by the merchant to the customer + (in case of physical items, this point means that the merchant must provide the receipt again + in the future to the customer) +2. The user must be able to *share* what he bought; in other words, we want a URI which would + hold any information about the purchase (and therefore the contract), like which items the + user bought and any other relevant detail. This way, any person who may get in possession + of this URI may repeat the same purchase. + +In Taler terminology, we call an *offering URL* an URL of the merchant's website that triggers +the generation of a contract, being it automatically or requiring the user interaction. For example, +some merchants may implement the offering URL such that it just returns the contract's JSON, and +some other may implement it as a shopping chart page where the user can then confirm its purchase and +get the contract JSON. We call a *fulfillment URL* an URL of the merchant's website which implements +points 1. and 2. For example, let's say that Alice bought a movie and a picture, and the fulfillment URL +for this purchase is *http://merchant.example.com/fulfillment?x=8ru42*. Each time Alice visits +*http://merchant.example.com/fulfillment?x=8ru42* she gets the same movie and picture. If then Alice +decides to give Bob this URL and he visits it, then he can decide to buy or not the same movie and +picture. + +--------------- +Payment details +--------------- + +A payment process is triggered whenever the user visits a fulfillment URL and he has no rights +in the session state to get the items accounted in the fulfillment URL. Since each fulfillment +URL carries all the details useful to reconstruct a contract, the merchant reconstructs the contract +and sends back to the user's browser a `taler-execute-payment` DOM event, defined as follows: .. code-block:: tsref { - // Contract and cryptographic information - contract_wrapper: { - contract: Contract; - // base32 of the merchant's signature over this contract - merchant_sig: string; - // base32 of this contract's hashcode - H_contract: string; - }; - - // If true, the 'back-button' seen by the user when this contract is to be - // payed will not point to this HTML, but to the previous one. - replace_navigation: boolean - } - -2. The wallet's reaction is dual: it can either let the user pay for this contract, or - detect whether the user has already payed for this resource by looking at the `repurchase_correlation_id` - field in the contract. In the first case, the wallet stores `H_contract` in its local database. - If there is a match, the wallet starts a IIG by visiting the fulfillment URL associated with the - already-made payment (see :ref:`ffil`) - -3. The wallet visits the fulfillment URL (which indicated in the Contract). Since the merchant keeps - no state for any purchase, it needs relevant information in the fulfillment URL in order to - reconstruct the contract and send the payment to the backend. This information is implicit in the - mention of 'fulfillment URL'. - -4. When a fulfillment URL is visited, the merchant reconstructs the contract and sends back to - the user the a `taler-execute-payment` event which embeds the following object - - .. code-block:: tsref - - { - // base32 of the Contract's hashcode + // base32 encoding of the Contract's hashcode H_contract: string; - // URL where to send deposit permission + // URL where to send the deposit permission (AKA coins) pay_url: string; - // Used in 'IIG by fulfillment URL' + // Offering URL offering_url: string; } -5. The wallet sends the deposit permission to `pay_url` - -6. If the payment is successful, then the merchant sets the state for the bought - item to `payed` and communicate the outcome to the wallet (see :ref:`merchant API ` for - involved HTTP codes and JSONs) - -7. Finally, the wallet can visit again the fulfillment URL and get the payed resource - thanks to the `payed` state - -.. _ffil: - ------------------------- -IIG by `fulfillment` URL ------------------------- - -We stress again that the fulfillment URL contains all the information a merchant needs -to reconstruct a contract. - -0. If the state associated to the resource requested is `payed`, get the wanted resource. - -1. The user visits a fulfillment URL - -2. The merchant replies with the same data structure shown in point 4 above - -3. The wallet checks if `H_contract` already exists in its database. If it does not exist, - then the wallet will automatically visit the offering URL (by looking at the `offering_url` - field) and all the process will restart as in point 1 above. Typically, this occurs when a - user visits a fulfillment URL gotten from some other user. If `H_contract` is known, then the - wallet takes the associated deposit permission from its database and the process will continue - as from point 5 above. Please note that the latter scenario is not double spending since the - same coins are spent on the same contract. +This event is listened to by the wallet which can take two decisions based on the `H_contract` +field: if `H_contract` is known to the wallet, then the user has already accepted the contract +for this purchase and the wallet will send a deposit permission to `pay_url`. If that is not the +case, then the wallet will visit the `offering_url` and the user will decide whether or not to +accept the contract. Once `pay_url` receives and approves the deposit permission, it sets the session +state for the claimed item(s) to ``payed`` and now the wallet can point again the browser to the +fulfillment URL and finally get the claimed item(s). It's worth noting that each deposit permission +is associated with a contract and the wallet can reuse the same deposit permission to get the item(s) +mentioned in the contract without spending new coins. -- cgit v1.2.3 From 9ea30f41d0b9e1688fc62089b135b8b1e1aafa66 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 6 Jul 2016 18:14:20 +0200 Subject: contract description as of #4118 --- integration-merchant.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/integration-merchant.rst b/integration-merchant.rst index 999fe411..a035089f 100644 --- a/integration-merchant.rst +++ b/integration-merchant.rst @@ -50,9 +50,11 @@ Payment details --------------- A payment process is triggered whenever the user visits a fulfillment URL and he has no rights -in the session state to get the items accounted in the fulfillment URL. Since each fulfillment -URL carries all the details useful to reconstruct a contract, the merchant reconstructs the contract -and sends back to the user's browser a `taler-execute-payment` DOM event, defined as follows: +in the session state to get the items accounted in the fulfillment URL. Note that when the user is +not visiting a fulfillment URL he got from someone else, it is the wallet which points the browser +to a fulfillment URL after the user accepts the contract. Since each fulfillment URL carries all the +details useful to reconstruct a contract, the merchant reconstructs the contract and sends back to +the user's browser a `taler-execute-payment` DOM event, defined as follows: .. code-block:: tsref @@ -76,3 +78,22 @@ state for the claimed item(s) to ``payed`` and now the wallet can point again th fulfillment URL and finally get the claimed item(s). It's worth noting that each deposit permission is associated with a contract and the wallet can reuse the same deposit permission to get the item(s) mentioned in the contract without spending new coins. + +------------ +The contract +------------ + +As said, the offering URL is a location where the user must pass by in order to get a contract, and +the contract is handed by the merchant to the browser by the mean of a `taler-confirm-contract` DOM +event, defined as follows: + + .. code-block:: tsref + + { + // The contract as returned by the merchant backend, + // having the following fields: + // 'contract': the contract itself (FIXME link this definition to where contract is defined) + // 'H_contract': the hash of 'contract' + // 'merchant_sig': the signature over the contract made by the merchant + contract_wrapper: Object; + } -- cgit v1.2.3 From cd72f3917f27ccccae1bc89aee898ac1c6b84d32 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 6 Jul 2016 19:14:01 +0200 Subject: (partly) adapting blog description to Python merchant --- example-essay-store.rst | 59 ++++++++++++++++++------------------------------- 1 file changed, 22 insertions(+), 37 deletions(-) diff --git a/example-essay-store.rst b/example-essay-store.rst index 042c5233..f3439cc8 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -76,19 +76,19 @@ some general insight on terms and interactions between components. This section describes how the demonstrator essay store interacts with the Taler system. As for Taler's terminology, the demonstrator essay store is an example of `frontend`. -This demonstrator lies in `examples/blog` of `git://taler.net/merchant/examples/blog` +This demonstrator's code 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 article is a reference to an `offering -URL` (see :ref:`byoffer`). In particular, this offering URL has the following format: +URL`. In particular, this offering URL has the following format: `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId` It is worth noting that in our implementation the `offering` and the `fulfillment` URLs -differ only respect to the parameters given to the path `/essay_fulfillment.php`. Namely, -the offering URL becomes a fulfillment URL whenever the user adds the parameters needed to -reconstruct the contract, which are `tid` (transaction id) and `timestamp` -(see :ref:`contract`, and :ref:`ffil`). For the sake of completeness, +differ only respect to the parameters given to the path `/essay_fulfillment.php`, therefore +are served by the same script. In detail, the offering URL becomes a fulfillment URL whenever +the user adds the parameters needed to reconstruct the contract, which are `tid` (transaction id) +and `timestamp`. For the sake of completeness, `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId&tid=3489×tamp=8374738` @@ -97,37 +97,22 @@ would be a fulfillment URL. Once the user visits the offering URL by clicking on some article's title, the merchant -1. checks if the state associated to this article corresponds to "payed". If this is the - case, point 7. is triggered, which is what happens when point 0 of :ref:`byoffer` is true. - -2. checks if the user gave additional parameters to the URL above, actually making it a - fulfillment URL. If so, jump to point `y`. - -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; 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:`byoffer`. - -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). - -5. the same script as in point 1. gets executed, but this time it detects that the user is visiting - a fulfillment URL. The script can now reconstruct the contract and store its hash in the state. - The hash is stored in an associative array having resource names as keys; in this case the key - `articleId` points to the contract's hash. This way is easier to detect if a resource which is - to be payed is actually mentioned in the deposit permission. Without this control, a malicious - wallet can send a deposit permission for `articleA` and get the resource `articleB`, see point 6. - As a last step, the script returns a page which fires a `taler-execute-payment` event in the user's - browser carrying the same data structure as in point 4. of :ref:`byoffer`. - Note that both in point 3. and 5. the HTML page returned is the same, namely it is the page showing - the credit card payment. It is designed so that it is possible to `inject` the event to fire at the - user's browser. So in point 3. the injected event is `taler-confirm-contract`, and in point 5. is - `taler-execute-payment`. This way if the Taler wallet responds to the event, then the payment is - kept Taler-style, otherwise the user just sees a credit card form (without making further requests). +1. checks if the state associated to this article corresponds to ``payed``. If this is the + case, just return to the user the article. + +2. figures out whether the user is visiting a offering or a fulfillment URL + +3. if it is a offering URL being visited then return a certain page offering the contract via + `taler-confirm-contract` event (FIXME link); if it is a fulfillment URL, then return the same + page which offers a `taler-execute-contract` event (FIXME link) instead. In both cases, the page + returned to the browser can detect if there is no wallet active, and will abort the payment in + that case. + +4. the wallet now points the user's browser to the fulfillment URL associated with this purchase + (the fulfillment URL is indicated in the contract) + +5. the website detects that the user is visiting now a fulfillment URL and creates an entry in + the session state about `articleId`. FIXME To be finished. 6. the wallet POSTs the deposit permission to `pay_url`, which is -- cgit v1.2.3 From 358c2caefbce591265b414b6e0557446b708bdb7 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 8 Jul 2016 11:36:43 +0200 Subject: removing payment protocol steps from blog's example page, as they are already described elsewhere --- api-exchange.rst | 2 + example-essay-store.rst | 120 +++++------------------------------------------- 2 files changed, 14 insertions(+), 108 deletions(-) diff --git a/api-exchange.rst b/api-exchange.rst index fab955de..11ee8926 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -442,6 +442,7 @@ exchange. history: TransactionHistoryItem[] } +.. _deposit-par: -------------------- Deposit @@ -456,6 +457,7 @@ denomination. .. _deposit: + .. http:POST:: /deposit Deposit the given coin and ask the exchange to transfer the given :ref:`amount` diff --git a/example-essay-store.rst b/example-essay-store.rst index f3439cc8..a780cdc2 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -16,123 +16,27 @@ 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. - -.. - Describing implementation of the above scenario - --------------- -Before reading --------------- To properly understand this example, the reader should be familiar with Taler's terminology; in particular, definitions like `contract`, `fulfillment URL`, `offering URL`, `IIG` and `deposit permission`, -are assumed to be known. Refer to :ref:`contract`, :ref:`payprot` and :ref:`deposit` in order to get +are assumed to be known. Refer to :ref:`contract`, :ref:`payprot` and :ref:`deposit-par` in order to get some general insight on terms and interactions between components. This section describes how the demonstrator essay store interacts with the Taler system. As for Taler's terminology, the demonstrator essay store is an example of `frontend`. -This demonstrator's code lies in `examples/blog` of `git://taler.net/merchant/examples/blog` +This demonstrator's code is hosted at `git://taler.net/merchant-frontends/talerfrontends/blog/` and is +implemented in Python. The essay store, available at https://blog.demo.taler.net, is such that its homepage -is a list of buyable articles and each article is a reference to an `offering -URL`. In particular, this offering URL has the following format: - - `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId` - -It is worth noting that in our implementation the `offering` and the `fulfillment` URLs -differ only respect to the parameters given to the path `/essay_fulfillment.php`, therefore -are served by the same script. In detail, the offering URL becomes a fulfillment URL whenever -the user adds the parameters needed to reconstruct the contract, which are `tid` (transaction id) -and `timestamp`. For the sake of completeness, - - - `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId&tid=3489×tamp=8374738` - -would be a fulfillment URL. - -Once the user visits the offering URL by clicking on some article's title, the merchant - -1. checks if the state associated to this article corresponds to ``payed``. If this is the - case, just return to the user the article. - -2. figures out whether the user is visiting a offering or a fulfillment URL - -3. if it is a offering URL being visited then return a certain page offering the contract via - `taler-confirm-contract` event (FIXME link); if it is a fulfillment URL, then return the same - page which offers a `taler-execute-contract` event (FIXME link) instead. In both cases, the page - returned to the browser can detect if there is no wallet active, and will abort the payment in - that case. - -4. the wallet now points the user's browser to the fulfillment URL associated with this purchase - (the fulfillment URL is indicated in the contract) - -5. the website detects that the user is visiting now a fulfillment URL and creates an entry in - the session state about `articleId`. FIXME To be finished. - -6. the wallet POSTs the deposit permission to `pay_url`, which is - - `https://blog.demo.taler.net/essay_pay.php?article=articleId` - - This step is responsible for setting the state for `articleId` as payed; to that end it uses - `articleId` as the key to get `H_contract` from the state and checks if `H_contract` equals - the contract's hash contained in the deposit permission. If they are equal, then the deposit - permission is forwarded to the backend. If the backend return a HTTP status 200, then `essay_pay.php` - sets the state for `articleId` as payed and notify the wallet about the payment's outcome. - If the backend reports any problem, `essay_pay.php` will just forward the data gotten from the - backend to the wallet, which will be in charge of managing the error. +is a list of titles from buyable articles and each title links to an `offering URL`. +In particular, the offering URL has the following format: -7. the wallet visit the fulfillment URL, but now the state for `articleId` is set to payed, so the - script will just show the wanted article. + `https://blog.demo.taler.net/essay/article_title` - `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId&tid=3489×tamp=8374738` +As for the fulfillment URL, it matches the initial part of an offering URL, but contains also +those parameters needed to reconstruct the contract, which are `tid` (transaction id) and `timestamp`. +So a fulfillment URL looks like: ----------------------- -IIG by fulfillment URL ----------------------- + `https://blog.demo.taler.net/essay/article_title?tid=3489×tamp=8374738` -TBD +We did not need to include any further details in the fulfillment URL because most of them +do not change in the time, and for simplicity all the articles have the same price. -- cgit v1.2.3 From bedb4fbbacf9e69e0fcdd5585ab61f066a598bbf Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 8 Jul 2016 11:45:13 +0200 Subject: needed link --- integration-merchant.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/integration-merchant.rst b/integration-merchant.rst index a035089f..4372dc36 100644 --- a/integration-merchant.rst +++ b/integration-merchant.rst @@ -90,10 +90,7 @@ event, defined as follows: .. code-block:: tsref { - // The contract as returned by the merchant backend, - // having the following fields: - // 'contract': the contract itself (FIXME link this definition to where contract is defined) - // 'H_contract': the hash of 'contract' - // 'merchant_sig': the signature over the contract made by the merchant - contract_wrapper: Object; + contract_wrapper: Offer; } + +Check at :ref:`contract` how the `Offer` interface is defined. -- cgit v1.2.3 From eb162a22c2d98c47003c51796cf2b1b0f04d52e6 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 8 Jul 2016 11:48:08 +0200 Subject: previous commit unneeded --- integration-merchant.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/integration-merchant.rst b/integration-merchant.rst index 4372dc36..b4e623a9 100644 --- a/integration-merchant.rst +++ b/integration-merchant.rst @@ -92,5 +92,3 @@ event, defined as follows: { contract_wrapper: Offer; } - -Check at :ref:`contract` how the `Offer` interface is defined. -- cgit v1.2.3 From cf15752157a05b21033ce8140752d022afb42d72 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 8 Jul 2016 14:51:51 +0200 Subject: addressing #4600 and other parts with the same problem --- api-merchant.rst | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/api-merchant.rst b/api-merchant.rst index 71f9a302..9c1adf9b 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -23,9 +23,9 @@ Merchant API Before reading the API reference documentation, it is suggested to read the :ref:`merchant-arch` ------------------------------- +--------------------- The Frontent HTTP API ------------------------------- +--------------------- .. http:get:: contract_url @@ -71,6 +71,9 @@ The Frontent HTTP API // maximum fees merchant agreed to cover as per the contract max_fee: Amount; + // The merchant instance which is going to receive the final wire transfer. See paragraph `Merchant Instances` + receiver: string; + // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT merchant_sig: EddsaSignature; @@ -143,20 +146,20 @@ The following API are made available by the merchant's `backend` to the merchant **Request:** - The `proposition` that is to be sent from the frontend is a `contract` object without the fields + The `proposition` that is to be sent from the frontend is a `contract` object *without* the fields * `exchanges` * `auditors` * `H_wire` * `merchant_pub` - The `backend` then completes this information based on its configuration. + The frontend may or may not provide a `receiver` field in the proposition, depending on its logic. + The ``default`` instance will be used if no `receiver` field is found by the backend. **Response** :status 200 OK: - The backend has successfully created the contract. It responds with an :ref:`offer `. This request should virtually always be successful. - On success, the `frontend` should pass this response verbatim to the wallet. + The backend has successfully created the contract. It responds with an :ref:`offer `. On success, the `frontend` should pass this response verbatim to the wallet. :status 403 Forbidden: The frontend used the same transaction ID twice. This is only allowed if the response from the backend was lost ("instant" replay), but to assure that frontends usually create fresh transaction IDs this is forbidden if the contract was already paid. So attempting to have the backend sign a contract for a contract that was already paid by a wallet (and thus was generated by the frontend a "long" time ago), is forbidden and results in this error. Frontends must make sure that they increment the transaction ID properly and persist the largest value used so far. @@ -225,7 +228,7 @@ The following API are made available by the merchant's `backend` to the merchant **Request:** :query id: ID of the transaction we want to trace (an integer) - + :query receiver: identificative token for the merchant instance which is to be tracked (optional). See :ref:`instances`. **Response:** :status 200 OK: @@ -282,6 +285,20 @@ Encodings Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`. +.. _instances: + +------------------ +Merchant Instances +------------------ + +Any backend can account for multiple bank accounts, and we call `instance` or `receiver` (interchangeably) +any of those bank accounts. The backend needs that due to the ability we give to a merchant to route money +(he earns through Taler) to multiple bank accounts, depending on his will. For example, a donation shop using +Taler needs to know any bank account of any entity which is going to receive money through his website. That +happens because when the merchant deposits coins to the exchange, he must provide bank details to it about the +money receiver, see :ref:`deposit-par`. + + .. _contract: Offer and Contract @@ -359,7 +376,11 @@ The `contract` must have the following structure: // More info about the merchant, see below merchant: Merchant; - // The hash of the merchant's wire details. + // Which instance is participating in this contract. See the paragraph `Merchant Instances`. + // This field is optional, as the "default" instance is not forced to provide any `receiver` identificator. + receiver: string; + + // The hash of the merchant instance's wire details. H_wire: HashCode; // Any exchanges audited by these auditors are accepted by the merchant. -- cgit v1.2.3 From bbbde6979f7e8f7fd22e5c2e7be550ed79408be0 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 11 Aug 2016 23:36:03 +0200 Subject: update DB schema --- exchange-db.png | Bin 202763 -> 198095 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/exchange-db.png b/exchange-db.png index de4c6570..ddc25591 100644 Binary files a/exchange-db.png and b/exchange-db.png differ -- cgit v1.2.3