Restructuring

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
+wallet.
+
+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.