prebuilt: update

1 files changed, 348 insertions, 0 deletions

diff --git a/texinfo/taler-bank.texi b/texinfo/taler-bank.texi
new file mode 100644
index 00000000..78293b57
--- /dev/null
+++ b/texinfo/taler-bank.texi
@@ -0,0 +1,348 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename taler-bank.info
+@documentencoding UTF-8
+@ifinfo
+@*Generated by Sphinx 2.2.0.@*
+@end ifinfo
+@settitle Taler Bank Manual
+@defindex ge
+@paragraphindent 0
+@exampleindent 4
+@finalout
+@dircategory CATEGORY
+@direntry
+* MENU ENTRY: (taler-bank.info). DESCRIPTION
+@end direntry
+
+@definfoenclose strong,`,'
+@definfoenclose emph,`,'
+@c %**end of header
+
+@copying
+@quotation
+GNU Taler 0.6.0pre1, Sep 18, 2019
+
+GNU Taler team
+
+Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)
+@end quotation
+
+@end copying
+
+@titlepage
+@title Taler Bank Manual
+@insertcopying
+@end titlepage
+@contents
+
+@c %** start of user preamble
+
+@c %** end of user preamble
+
+@ifnottex
+@node Top
+@top Taler Bank Manual
+@insertcopying
+@end ifnottex
+
+@c %**start of body
+@anchor{taler-bank-manual doc}@anchor{0}
+@menu
+* Introduction:: 
+* Reference:: 
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* About GNU Taler:: 
+* About this manual:: 
+
+Reference
+
+* Bank-Wallet interaction:: 
+* Bank-Exchange interaction:: 
+
+Bank-Exchange interaction
+
+* Withdraw:: 
+* Exchange pays merchant:: 
+
+@end detailmenu
+@end menu
+
+@node Introduction,Reference,Top,Top
+@anchor{taler-bank-manual gnu-taler-bank-manual}@anchor{1}@anchor{taler-bank-manual introduction}@anchor{2}
+@chapter Introduction
+
+
+@menu
+* About GNU Taler:: 
+* About this manual:: 
+
+@end menu
+
+@node About GNU Taler,About this manual,,Introduction
+@anchor{taler-bank-manual about-gnu-taler}@anchor{3}
+@section 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).
+
+@node About this manual,,About GNU Taler,Introduction
+@anchor{taler-bank-manual about-this-manual}@anchor{4}
+@section 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.
+
+@node Reference,,Introduction,Top
+@anchor{taler-bank-manual id1}@anchor{5}@anchor{taler-bank-manual reference}@anchor{6}
+@chapter Reference
+
+
+@menu
+* Bank-Wallet interaction:: 
+* Bank-Exchange interaction:: 
+
+@end menu
+
+@node Bank-Wallet interaction,Bank-Exchange interaction,,Reference
+@anchor{taler-bank-manual bank-002dwallet-interaction}@anchor{7}@anchor{taler-bank-manual bank-wallet-interaction}@anchor{8}
+@section Bank-Wallet interaction
+
+
+The HTTP status code @code{202 Accepted} can be used by the bank website to
+trigger operations in the user agent. The operation is determined by the
+@code{X-Taler-Operation} header. The following operations are understood:
+
+
+@table @asis
+
+@item @code{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:
+
+
+@itemize -
+
+@item 
+@code{X-Taler-Callback-Url}: URL that the wallet will visit when the
+reserve was created and the user has selected an exchange.
+
+@item 
+@code{X-Taler-Wt-Types}: JSON-encoded array of wire transfer types
+that this bank supports.
+
+@item 
+@code{X-Taler-Amount}: The amount that will be transferred to the
+reserve.
+
+@item 
+@code{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.
+@end itemize
+
+The following header is optional:
+
+
+@itemize -
+
+@item 
+@code{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.
+@end itemize
+
+On successful reserve creation, the wallet will navigate to the
+callback URL (effectively requesting it with a GET) with the
+following additional request parameters:
+
+
+@itemize -
+
+@item 
+@code{exchange}: The URL of the exchange selected by the user
+
+@item 
+@code{wire_details}: The wire details of the exchange.
+
+@item 
+@code{reserve_pub}: The reserve public key that the bank should
+transmit to the exchange when transmitting the funds.
+@end itemize
+
+@item @code{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 @code{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.
+@end table
+
+@node Bank-Exchange interaction,,Bank-Wallet interaction,Reference
+@anchor{taler-bank-manual bank-002dexchange-interaction}@anchor{9}@anchor{taler-bank-manual bank-exchange-interaction}@anchor{a}
+@section 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.
+
+@menu
+* Withdraw:: 
+* Exchange pays merchant:: 
+
+@end menu
+
+@node Withdraw,Exchange pays merchant,,Bank-Exchange interaction
+@anchor{taler-bank-manual withdraw}@anchor{b}
+@subsection 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 @code{/admin/add/incoming}
+API, providing those arguments it got along the @code{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:
+@code{execution_date} (a operation’s timestamp), and @code{transfer_details}
+(just a "seed" to make unique the operation). See
+@indicateurl{https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions}.
+
+The polling mechanism is possbile thanks to the @code{/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.
+
+
+@table @asis
+
+@item @code{GET /history}
+
+Ask the bank to return a list of money transactions related to a
+caller’s bank account.
+
+
+@itemize -
+
+@item 
+@code{auth} a string indicating the authentication method to use;
+only @code{"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:
+@code{X-Taler-Bank-Username} and @code{X-Taler-Bank-Password}, which
+will contain those plain text credentials.
+
+@item 
+@code{delta} returns the first @code{N} records younger (older) than
+@code{start} if @code{+N} (@code{-N}) is specified.
+
+@item 
+@code{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.
+
+@item 
+@code{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
+
+@item 
+@code{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
+@end itemize
+@end table
+
+@node Exchange pays merchant,,Withdraw,Bank-Exchange interaction
+@anchor{taler-bank-manual exchange-pays-merchant}@anchor{c}
+@subsection Exchange pays merchant
+
+
+To allow the exchange to send payments to a merchant, the bank exposes
+the @code{/admin/add/incoming} API to exchanges.
+
+
+@table @asis
+
+@item @code{POST /admin/add/incoming}
+
+Ask the bank to transfer money from the caller’s account to the
+receiver’s.
+
+
+@itemize -
+
+@item 
+@code{auth} a string indicating the authentication method to use;
+only @code{"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:
+@code{X-Taler-Bank-Username} and @code{X-Taler-Bank-Password}, which
+will contain those plain text credentials.
+
+@item 
+@code{amount} a JSON object complying to the Taler amounts layout.
+Namely, this object must contain the following fields: @code{value}
+(number), @code{fraction} (number), and @code{currency} (string).
+
+@item 
+@code{exchange_url} a string indicating the calling exchange base
+URL. The bank will use this value to define wire transfers subject
+lines.
+
+@item 
+@code{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: @code{'wtid exchange_url'}.
+
+@item 
+@code{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.
+
+@item 
+@code{credit_account} bank account number that will receive the
+transfer. Tipically the merchant account number.
+@end itemize
+@end table
+
+@c %**end of body
+@bye