summaryrefslogtreecommitdiff
path: root/taler-bank.rst
diff options
context:
space:
mode:
Diffstat (limited to 'taler-bank.rst')
-rw-r--r--taler-bank.rst190
1 files changed, 190 insertions, 0 deletions
diff --git a/taler-bank.rst b/taler-bank.rst
new file mode 100644
index 00000000..c85e0aa4
--- /dev/null
+++ b/taler-bank.rst
@@ -0,0 +1,190 @@
+The GNU Taler bank manual
+#########################
+
+Introduction
+============
+
+About GNU Taler
+---------------
+
+GNU Taler is an open protocol for an electronic payment system with a
+free software reference implementation. GNU Taler offers secure, fast
+and easy payment processing using well understood cryptographic
+techniques. GNU Taler allows customers to remain anonymous, while
+ensuring that merchants can be held accountable by governments. Hence,
+GNU Taler is compatible with anti-money-laundering (AML) and
+know-your-customer (KYC) regulation, as well as data protection
+regulation (such as GDPR).
+
+About this manual
+-----------------
+
+This manual documents how the demonstrator bank interoperates with the
+other GNU Taler components. The demonstrator bank implements a simple
+closed banking system for the purpose of illustrating how GNU Taler
+works in the Taler demo. It could also be used as a starting point for a
+local/regional currency. Finally, “real” banks might use it as a
+reference implementation for a tight integration with the GNU Taler
+wallet.
+
+.. _Reference:
+
+Reference
+=========
+
+.. _Bank_002dWallet-interaction:
+
+Bank-Wallet interaction
+-----------------------
+
+The HTTP status code ``202 Accepted`` can be used by the bank website to
+trigger operations in the user agent. The operation is determined by the
+``X-Taler-Operation`` header. The following operations are understood:
+
+``create-reserve``
+ Ask the Taler wallet to create a reserve and call back the bank with
+ the reserve public key. The following headers are mandatory:
+
+ - ``X-Taler-Callback-Url``: URL that the wallet will visit when the
+ reserve was created and the user has selected an exchange.
+
+ - ``X-Taler-Wt-Types``: JSON-encoded array of wire transfer types
+ that this bank supports.
+
+ - ``X-Taler-Amount``: The amount that will be transferred to the
+ reserve.
+
+ - ``X-Taler-Sender-Wire``: JSON-encoded wire account details of the
+ sender, that is the user that is currently logged in with the bank
+ and creates the reserve.
+
+ The following header is optional:
+
+ - ``X-Taler-Suggested-Exchange``: Exchange that the bank recommends
+ the customer to use. Note that this is a suggestion and can be
+ ignored by the wallet or changed by the user.
+
+ On successful reserve creation, the wallet will navigate to the
+ callback URL (effectively requesting it with a GET) with the
+ following additional request parameters:
+
+ - ``exchange``: The URL of the exchange selected by the user
+
+ - ``wire_details``: The wire details of the exchange.
+
+ - ``reserve_pub``: The reserve public key that the bank should
+ transmit to the exchange when transmitting the funds.
+
+``confirm-reserve``
+ To secure the operation, the (demo) bank then shows a "CAPTCHA page"
+ – a real bank would instead show some PIN entry dialog or similar
+ security method – where the customer can finally prove she their
+ identity and thereby confirm the withdraw operation to the bank.
+
+ Afterwards, the bank needs to confirm to the wallet that the user
+ completed the required steps to transfer funds to an exchange to
+ establish the reserve identified by the ``X-Taler-Reserve-Pub``
+ header.
+
+ This does not guarantee that the reserve is already created at the
+ exchange (since the actual money transfer might be executed
+ asynchronously), but it informs that wallet that it can start polling
+ for the reserve.
+
+.. _Bank_002dExchange-interaction:
+
+Bank-Exchange interaction
+-------------------------
+
+The interaction between a bank and the exchange happens in two
+situations: when a wallet withdraws coins, and when the exchange pays a
+merchant.
+
+Withdraw
+~~~~~~~~
+
+Once a withdrawal operation with the wallet has been confirmed, the the
+bank must wire transfer the withdrawn amount from the customer account
+to the exchange’s. After this operation is done, the exchange needs to
+be informed so that it will create the reserve.
+
+For the moment, the bank will use the exchange’s ``/admin/add/incoming``
+API, providing those arguments it got along the ``X-Taler-Callback-Url``
+URL. (In the future, the exchange will poll for this information.)
+However, the bank will define two additional values for this API:
+``execution_date`` (a operation’s timestamp), and ``transfer_details``
+(just a "seed" to make unique the operation). See
+https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions.
+
+The polling mechanism is possbile thanks to the ``/history`` API
+provided by the bank. The exchange will periodically use this API to see
+if it has received new wire transfers; upon receiving a new wire
+transfer, the exchange will automatically create a reserve and allow the
+money sender to withdraw.
+
+``GET /history``
+ Ask the bank to return a list of money transactions related to a
+ caller’s bank account.
+
+ - ``auth`` a string indicating the authentication method to use;
+ only ``"basic"`` value is accepted so far. The username and
+ password credentials have to be sent along the HTTP request
+ headers. Namely, the bank will look for the following two headers:
+ ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
+ will contain those plain text credentials.
+
+ - ``delta`` returns the first ``N`` records younger (older) than
+ ``start`` if ``+N`` (``-N``) is specified.
+
+ - ``start`` according to delta, only those records with row id
+ strictly greater (lesser) than start will be returned. This
+ argument is optional; if not given, delta youngest records will be
+ returned.
+
+ - ``direction`` optional argument taking values debit or credit,
+ according to the caller willing to receive both incoming and
+ outgoing, only outgoing, or only incoming records
+
+ - ``account_number`` optional argument indicating the bank account
+ number whose history is to be returned. If not given, then the
+ history of the calling user will be returned
+
+Exchange pays merchant
+~~~~~~~~~~~~~~~~~~~~~~
+
+To allow the exchange to send payments to a merchant, the bank exposes
+the ``/admin/add/incoming`` API to exchanges.
+
+``POST /admin/add/incoming``
+ Ask the bank to transfer money from the caller’s account to the
+ receiver’s.
+
+ - ``auth`` a string indicating the authentication method to use;
+ only ``"basic"`` value is accepted so far. The username and
+ password credentials have to be sent along the HTTP request
+ headers. Namely, the bank will look for the following two headers:
+ ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
+ will contain those plain text credentials.
+
+ - ``amount`` a JSON object complying to the Taler amounts layout.
+ Namely, this object must contain the following fields: ``value``
+ (number), ``fraction`` (number), and ``currency`` (string).
+
+ - ``exchange_url`` a string indicating the calling exchange base
+ URL. The bank will use this value to define wire transfers subject
+ lines.
+
+ - ``wtid`` a alphanumeric string that uniquely identifies this
+ transfer at the exchange database. The bank will use this value
+ too to define wire transfers subject lines. Namely, subject lines
+ will have the following format: ``'wtid exchange_url'``.
+
+ - ``debit_account`` number indicating the exchange bank account.
+ NOTE: this field is currently ignored, as the bank can retrieve
+ the exchange account number from the login credentials. However,
+ in future release, an exchange could have multiple account at the
+ same bank, thereby it will have the chance to specify any of them
+ in this field.
+
+ - ``credit_account`` bank account number that will receive the
+ transfer. Tipically the merchant account number.