path: root/integration-merchant.rst
diff options
authorMarcello Stanisci <>2016-07-06 17:47:16 +0200
committerMarcello Stanisci <>2016-07-06 17:47:16 +0200
commit36c085b4766cb4ca84da4c65c5cd8e0c16046961 (patch)
treed282e387e9803adc30b4840993ea3b3e1c01df77 /integration-merchant.rst
parentbba5907f359908d0cb01ef48a7f994eeb93ce081 (diff)
simplifying payment protocol description
Diffstat (limited to 'integration-merchant.rst')
1 files changed, 47 insertions, 101 deletions
diff --git a/integration-merchant.rst b/integration-merchant.rst
index 76a9ae5..999fe41 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 **. Each time Alice visits
+** 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
+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 <pay>` 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.