documenting bank-exchange interaction/API.

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 **********************************************************