diff options
author | Marcello Stanisci <marcello.stanisci@inria.fr> | 2017-07-26 12:30:12 +0200 |
---|---|---|
committer | Marcello Stanisci <marcello.stanisci@inria.fr> | 2017-07-26 12:30:12 +0200 |
commit | 5012f75915e1cd09c7d5f5fe2368ef1fca112f24 (patch) | |
tree | f1b3443979125c1604ef9e92fe4ab8e0a80af9ca /doc | |
parent | d20ff10975eb3bc6be3c449ff17a03510ea3b3b3 (diff) | |
download | bank-5012f75915e1cd09c7d5f5fe2368ef1fca112f24.tar.gz bank-5012f75915e1cd09c7d5f5fe2368ef1fca112f24.tar.bz2 bank-5012f75915e1cd09c7d5f5fe2368ef1fca112f24.zip |
documenting bank-exchange interaction/API.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/taler-bank.texi | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/doc/taler-bank.texi b/doc/taler-bank.texi index ccb91c3..f85cb64 100644 --- a/doc/taler-bank.texi +++ b/doc/taler-bank.texi @@ -166,6 +166,81 @@ polling for the reserve. @end table +@node Bank-Exchange interaction +@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. + +@subsection Withdraw +In the context of the @code{create-reserve} command, upon confirming the +exchange, the wallet visits the @code{X-Taler-Callback-Url}, including the +following arguments in the URL: @code{amount}, @code{exchange_url}, +@code{reserve_pub}, @code{exchange_account_number}, @code{sender_wiredetails}. + +To secure the operation, the bank then shows a "CAPTCHA page" -- any bank +is free to choose its own security method -- where the customer can finally +prove she is not a bot and finally confirm the withdraw operation. + +Upon confirmation, the bank will firstly 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. + +To this purpose, 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. +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 @url{https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions}. + +The HTTP status code returned to the user agent is whatever status code +the exchange gives back for the call to @code{/admin/add/incoming}. However, +it's bank's responsibility to let the user know about the outcome. + +@subsection Exchange pays merchant + +To provide this service, the bank exposes the @code{/admin/add/incoming} +API to exchanges. + +@table @code + +@item POST /admin/add/incoming +Ask the bank to transfer money from the caller's account to +the receiver's. + +@itemize +This call accepts a JSON encoded body with the following fields. + +@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 ********************************************************** @c ******************* Appendices ************************* @c ********************************************************** |