path: root/doc/taler-bank.texi

\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})
@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 banks can integrate with GNU Taler.  At present, only the API between the
bank's website and the Taler wallet is described.  In the future, this manual will also discuss the
demo bank application and further details for the bank integration.


@node Reference
@chapter Reference

@menu
* Headers for HTTP 202::                 Headers for the 202 status code and their effect on the user agent's operation
@end menu

@node Headers for HTTP 202
@section Headers for HTTP 202
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 @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 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 overwritten
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
When triggering this operation, the bank confirms 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
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 **********************************************************

@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