path: root/taler-bank.rst
diff options
Diffstat (limited to 'taler-bank.rst')
1 files changed, 190 insertions, 0 deletions
diff --git a/taler-bank.rst b/taler-bank.rst
new file mode 100644
index 0000000..c85e0aa
--- /dev/null
+++ b/taler-bank.rst
@@ -0,0 +1,190 @@
+The GNU Taler bank manual
+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
+.. _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:
+ 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.
+ 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
+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
+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.