From 1a295029028853507c0a833864e2840f3512a678 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 12 Nov 2015 23:24:34 +0100 Subject: adding interaction wallet-bank (#4047) --- api-merchant.rst | 14 +----- api-mint.rst | 1 - banks.rst | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ index.rst | 1 + 4 files changed, 149 insertions(+), 14 deletions(-) create mode 100644 banks.rst diff --git a/api-merchant.rst b/api-merchant.rst index e82fd158..daf94c4f 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -252,25 +252,13 @@ for example by updating the DOM to enable the respective button. The following events are needed when one of the two parties leaves the scenario. -First, if the Taler extension is unloaded while the user is +If the Taler extension is unloaded while the user is visiting a checkout page, the page should listen for the .. js:data:: taler-unload event to hide the Taler payment option. -Secondly, when the Taler extension is active and the user closes or navigates -away from the checkout page, the page should listen to a - - .. js:data:: taler-navigating-away - -event, and reply with a - - .. js:data:: taler-checkout-away - -event, in order to notify the extension that the user is leaving a checkout -page, so that the extension can change its color back to its default. - The following source code highlights the key steps for adding the Taler signaling to a checkout page: diff --git a/api-mint.rst b/api-mint.rst index 02a06a29..81f000a5 100644 --- a/api-mint.rst +++ b/api-mint.rst @@ -718,7 +718,6 @@ Administrative API: Bank transactions :>json string error: the error message (`permission denied`) :>json string hint: hint as to why permission was denied - ------------ The Test API ------------ diff --git a/banks.rst b/banks.rst new file mode 100644 index 00000000..27ab6bc0 --- /dev/null +++ b/banks.rst @@ -0,0 +1,147 @@ +=================================== +Interaction with banks Web portals +=================================== + +This section describes the interactions that should occur between +a wallet and a bank which chooses to adapt its Web portal to interact +with the Taler wallet. This interaction is supposed to occur when +the user is sending a SEPA transfer to some mint (i.e. he is creating +a new reserve). + + .. note:: + For its being in early stage of development, the following protocol is + implemented inside the mint code, through a ad-hoc website. + +Through this interaction, the wallet can generate a new reserve's public +key and insert it into the 'subject' field of the transfer without manual +copy&paste. Secondly, the wallet is then able to fetch the amount to be +tranferred to the mint directly from the Web form, in order to poll the mint +to check if the desired amount has been transferred. + +---------------------- +Mutual acknowledgement +---------------------- + +The mutual acknowledgement between a wallet and a bank portal occurs when +the user is on the page which hosts the SEPA form, and is realized by the +mean of JavaScript signals issued on the `body` HTML element. + +When the bank wants to notify to a wallet, it sends the following event: + + .. js:data:: taler-wire-probe + +This event must be sent from a callback for the `onload` event of the +`body` element, otherwise the extension would have not time to +register a listener for this event. It also needs to be sent when +the Taler extension is dynamically loaded, like when the user activates +the extension while he is on the SEPA form page. This is done by +listening for the + + .. js:data:: taler-load + +event. If the Taler extension is present, it will respond with a + + .. js:data:: taler-wallet-present + +event. The handler should then activate its mechanism to trigger the generation +of a new reserve key in the wallet, for example by updating the DOM to enable a +dedicated button. + +If the Taler extension is unloaded while the user is visiting a SEPA form page, +the page should listen for a + + .. js:data:: taler-unload + +event, in order to hide the previously enabled button. + +------------------------- +How to trigger the wallet +------------------------- + +This interaction will make the wallet generate a new reserve public key as +well as paste this information inside the SEPA form. Lastly, it allows the +wallet to fetch the desired amount to be transferred to the mint from the +SEPA form. Typically, it is initiated by the user pushing a button. + +The wallet listens to a + + .. js:data:: taler-create-reserve + +event, through which it expects to receive the following object: + +.. sourcecode:: javascript + {input_amount: input-amount-id, + input_pub: input-pub-id} + +`input-amount-id` is the `id` attribute of the HTML `input` element which +hosts the amount to wire to the desired mint. Please note that the wallet will +only accept amounts of the form `n[.x[y]] CUR`, where `CUR` is the ISO code +of the specified currency. So it may be necessary for the bank's webmaster to +preprocess this data to give it to the wallet in the right format. The wallet +will fetch this element through the following event, triggere by the `onsubmit` +attribute: + + .. js:data:: reserve-submitted + +`input-pub-id` must be the `id` of the `input` element which represents this +SEPA transfer's "subject". + +The following source code highlights the key steps for adding the Taler button +to trigger the wallet on a SEPA form page: + +.. sourcecode:: javascript + + function has_taler_wallet_callback(aEvent){ + // This function is called if a Taler wallet is available. + // suppose the radio button for the Taler option has + // the DOM ID attribute 'taler-wallet-trigger' + var tbutton = document.getElementById("taler-wallet-trigger"); + tbutton.removeAttribute("disabled"); + }; + + function taler_wallet_load_callback(aEvent){ + // let the Taler wallet know that this is a SEPA form page + // which supports Taler (the extension will have + // missed our initial 'taler-wire-probe' from onload()) + document.body.dispatchEvent(new Event('taler-wire-probe')); + }; + + function taler_wallet_unload_callback(aEvent){ + // suppose the button which triggers the wallet has + // the DOM ID attribute 'taler-wallet-trigger' + var tbutton = document.getElementById("taler-wallet-trigger"); + tbutton.setAttribute("disabled", "true"); + }; + +.. sourcecode:: html + + + ... + + +Finally, the following snippet shows how to trigger the wallet to make it +fetch the amount from the DOM + +.. sourcecode:: html + +
+ .. +
+ + diff --git a/index.rst b/index.rst index 597bb96d..991da528 100644 --- a/index.rst +++ b/index.rst @@ -31,6 +31,7 @@ Protocol Specification: api-mint api-merchant + banks Implementation: -- cgit v1.2.3