[GNUnet-SVN] [taler-bank] branch master updated: documenting bank-exchange interaction/API.

[gnunet]

This is an automated email from the git hooks/post-receive script.

marcello pushed a commit to branch master
in repository bank.

The following commit(s) were added to refs/heads/master by this push:
     new 5012f75  documenting bank-exchange interaction/API.
5012f75 is described below

commit 5012f75915e1cd09c7d5f5fe2368ef1fca112f24
Author: Marcello Stanisci <address@hidden>
AuthorDate: Wed Jul 26 12:30:12 2017 +0200

    documenting bank-exchange interaction/API.
---
 doc/taler-bank.texi | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

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
 
address@hidden Bank-Exchange interaction
address@hidden 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.
+
address@hidden 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},
address@hidden, @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.
+
address@hidden Exchange pays merchant
+
+To provide this service, the bank exposes the @code{/admin/add/incoming}
+API to exchanges.
+
address@hidden @code
+
address@hidden POST /admin/add/incoming
+Ask the bank to transfer money from the caller's account to
+the receiver's.
+
address@hidden
+This call accepts a JSON encoded body with the following fields.
+
address@hidden @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.
+
address@hidden @code{amount} a JSON object complying to the Taler amounts 
layout.
+Namely, this object must contain the following fields: @code{value} (number),
address@hidden (number), and @code{currency} (string).
+
address@hidden @code{exchange_url} a string indicating the calling exchange base
+URL.  The bank will use this value to define wire transfers subject lines.
+
address@hidden @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:
address@hidden'wtid exchange_url'}.
+
address@hidden @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.
+
address@hidden @code{credit_account} bank account number that will receive the 
transfer.
+Tipically the merchant account number.
+
address@hidden itemize
+
address@hidden table
+
+
 @c **********************************************************
 @c *******************  Appendices  *************************
 @c **********************************************************

-- 
To stop receiving notification emails like this one, please contact
address@hidden