diff options
Diffstat (limited to 'texinfo/taler-bank.texi')
| -rw-r--r-- | texinfo/taler-bank.texi | 267 |
1 files changed, 39 insertions, 228 deletions
diff --git a/texinfo/taler-bank.texi b/texinfo/taler-bank.texi index 075df81e..c2edaeca 100644 --- a/texinfo/taler-bank.texi +++ b/texinfo/taler-bank.texi @@ -3,7 +3,7 @@ @setfilename taler-bank.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 2.2.0.@* +@*Generated by Sphinx 3.4.3.@* @end ifinfo @settitle Taler Bank Manual @defindex ge @@ -21,11 +21,11 @@ @copying @quotation -GNU Taler 0.6.0pre1, Dec 20, 2019 +GNU Taler 0.8.0pre0, Jan 21, 2021 GNU Taler team -Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -50,7 +50,7 @@ Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Hars @anchor{taler-bank-manual doc}@anchor{0} @menu * Introduction:: -* Reference:: +* Headless Testing API Reference:: @detailmenu --- The Detailed Node Listing --- @@ -60,20 +60,10 @@ 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 +@node Introduction,Headless Testing API Reference,Top,Top @anchor{taler-bank-manual gnu-taler-bank-manual}@anchor{1}@anchor{taler-bank-manual introduction}@anchor{2} @chapter Introduction @@ -111,238 +101,59 @@ 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 - +@node Headless Testing API Reference,,Introduction,Top +@anchor{taler-bank-manual headless-testing-api-reference}@anchor{5} +@chapter Headless Testing API Reference -@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: +The demonstrator bank offers the following APIs to allow automated testing. These APIs should +be switched off during a production deployment. +@anchor{taler-bank-manual bank-register}@anchor{6} +@anchor{taler-bank-manual post--register}@anchor{7} +@deffn {HTTP Post} POST /register +This API provides programmatic user registration at the bank. -@itemize - +@strong{Request} The body of this request must have the format of a +@ref{8,,BankRegistrationRequest}. -@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. +@strong{Response} @table @asis -@item @code{GET /history} - -Ask the bank to return a list of money transactions related to a -caller’s bank account. +@item 200 OK@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1}: +The new user has been correctly registered. -@itemize - +@item 409 Conflict@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10}: -@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. +The username requested by the client is not available anymore. -@item -@code{delta} returns the first @code{N} records younger (older) than -@code{start} if @code{+N} (@code{-N}) is specified. +@item 400 Bad request@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1}: -@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 +Unacceptable characters were given for the username. See +@indicateurl{https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username} +for the accepted character set. @end table +@end deffn -@node Exchange pays merchant,,Withdraw,Bank-Exchange interaction -@anchor{taler-bank-manual exchange-pays-merchant}@anchor{c} -@subsection Exchange pays merchant - +@strong{Details} -To allow the exchange to send payments to a merchant, the bank exposes -the @code{/admin/add/incoming} API to exchanges. +@example +interface BankRegistrationRequest @{ + // Username to use for registration; max length is 150 chars. + username: string; -@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 + // Password to associate with the username. Any characters and + // any length are valid; next releases will enforce a minimum length + // and a safer characters choice. + password: string; +@} +@end example +@anchor{taler-bank-manual tsref-type-BankRegistrationRequest}@w{ } +@anchor{8}@w{ } @c %**end of body @bye |