\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename taler-bank.info
@include version.texi
@include syntax.texi
@settitle The GNU Taler manual for bank integration @value{VERSION}

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying
This manual is about integrating Taler with banking applications
and operating the demo bank software. (version @value{VERSION}, @value{UPDATED}),

Copyright @copyright{} 2017 Inria

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@c If your tutorial is published on paper by the FSF, it should include
@c The standard FSF Front-Cover and Back-Cover Texts, as given in
@c maintain.texi.
@c
@c Titlepage
@c
@titlepage
@title The GNU Taler bank manual
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Florian Dold (@email{florian.dold@@inria.fr})
@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents
@contents

@ifnottex
@node Top
@top The GNU Taler bank manual
@insertcopying
@end ifnottex

@menu
* Introduction::                                  What this manual is about
* Reference::                                     Bank integration reference


Appendices

* GNU-AGPL::                     The GNU Lesser General Public License says how you
                                 can use the code of the GNU Taler demo bank in your own projects.
* GNU-FDL::                      The GNU Free Documentation License says how you
                                 can copy and share the documentation of GNU Taler.

Indices

* Concept Index::               Index of concepts and programs.
@end menu


@node Introduction
@chapter Introduction

@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).


@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
@chapter Reference

@menu
* Bank-Wallet interaction::              Tight integration with the bank for withdrawal
* Bank-Exchange interaction::            Money flux to and from the Exchange
@end menu

@node Bank-Wallet interaction
@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:

@c maybe not use a table but subsections here?

@table @code
@item 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 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
@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

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 @url{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 @code

@item 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


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

@node GNU-AGPL
@unnumbered GNU-AGPL
@cindex license
@cindex AGPL
@include agpl.texi

@node GNU-FDL
@unnumbered GNU-FDL
@cindex license
@cindex GNU Free Documentation License
@include fdl-1.3.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye