From 12f0c8ca6c907850aa0457a5ddbdc4640a3b7a33 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 18 Sep 2019 19:06:49 +0200 Subject: prebuilt: update --- texinfo/taler-bank.texi | 348 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 texinfo/taler-bank.texi (limited to 'texinfo/taler-bank.texi') 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 -- cgit v1.2.3