path: root/integration-bank.rst
diff options
Diffstat (limited to 'integration-bank.rst')
1 files changed, 73 insertions, 0 deletions
diff --git a/integration-bank.rst b/integration-bank.rst
new file mode 100644
index 00000000..58015cf2
--- /dev/null
+++ b/integration-bank.rst
@@ -0,0 +1,73 @@
+Interaction with bank websites
+This section describes how bank websites can interact with the
+Taler wallet.
+Currently the following functionality is supported:
+ * Querying for the presence of a Taler wallet.
+ * Receiving change notifications from the Taler wallet.
+ * Creating a reserve.
+For JavaScript code examples, see :ref:`communication`.
+Presence Query
+The bank website queries the wallet's presence by sending a ``taler-wire-probe`` event. The
+event data should be `null`.
+If the wallet is present and active, it will respond with a ``taler-wallet-present`` event.
+Change Notification
+While the user agent is displaying a bank website, the user might deactivate or
+re-activate the wallet. A bank website *should* react to those events, and
+indicate to the user that they should (re-)enable if necessary.
+When the wallet is activated, the ``taler-wallet-load`` event is sent
+by the wallet. When the wallet is deactivated, the ``taler-wallet-unload`` event
+is sent by the wallet.
+Reserve Creation Request
+The bank website can request the creation of a :term:`reserve`. Note that the
+user will always be prompted by the wallet before a reserve is created in the
+As a result of the reserve creation request, the following steps will happen insequence:
+ 1. The wallet will prompt the user for the *mint base URL* and ask the user to
+ confirm creating the reserve.
+ 2. The wallet will create a key pair for the reserve.
+ 3. The wallet will make a request to the bank, containing
+ the reserve's public key and the mint base URL chosen by the user
+The bank should then take steps that will establish the reserve at the
+customer's requested mint. This could, depending on the bank and mint, either
+be a SEPA wire transfer or some other means.
+In response to the reserve creation request, the Taler wallet MAY cause the
+current document location to be changed, in order to navigate to a
+wallet-internal confirmation page.
+The bank requests reserve creation with the ``taler-create-reserve`` event.
+The event data must be a JavaScript ``object`` with the following fields:
+ * ``form_id``: The ``id`` of the ``form`` HTML element that contains data for the HTTP POST request
+ that confirms reserve creation with the bank.
+ * ``input_amount``: Amount of the reserve in the format ``N.C CUR``, where ``CUR`` is the
+ currency code.
+ * ``mint_rcv``: The ``id`` of the ``input`` HTML element in the reserve creation form
+ that will contain mint base URL for the reserve
+ * ``input_pub``: The ``id`` of the ``input`` HTML element in the reserve creation form
+ that will contain the reserve's public key.
+Note that the bank website MUST contain an HTML form with the data required for the request and
+input fields for receiving data from the mint.