diff options
author | Florian Dold <florian.dold@gmail.com> | 2019-08-29 13:32:36 +0200 |
---|---|---|
committer | Florian Dold <florian.dold@gmail.com> | 2019-08-29 13:32:36 +0200 |
commit | 4b82b7c171068c4722f10855391b9ca3a6ea20a9 (patch) | |
tree | 637afae238c00e8ca6beb8e690f13bf161da5c72 /taler-bank.rst | |
parent | ba9335ec4c3578fdebfbec3072396bcda29d3425 (diff) | |
download | docs-4b82b7c171068c4722f10855391b9ca3a6ea20a9.tar.gz docs-4b82b7c171068c4722f10855391b9ca3a6ea20a9.tar.bz2 docs-4b82b7c171068c4722f10855391b9ca3a6ea20a9.zip |
texinfo support
Diffstat (limited to 'taler-bank.rst')
-rw-r--r-- | taler-bank.rst | 190 |
1 files changed, 0 insertions, 190 deletions
diff --git a/taler-bank.rst b/taler-bank.rst deleted file mode 100644 index c85e0aa4..00000000 --- a/taler-bank.rst +++ /dev/null @@ -1,190 +0,0 @@ -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. |