summaryrefslogtreecommitdiff
path: root/taler-bank-manual.rst
blob: 4c1b5730a74a42eaf38f82cc42ece77654f61573 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
GNU Taler bank manual
#####################

Introduction
============

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

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.

.. _Reference:

Reference
=========

.. _Bank_002dWallet-interaction:

Bank-Wallet interaction
-----------------------

The HTTP status code ``202 Accepted`` can be used by the bank website to
trigger operations in the user agent. The operation is determined by the
``X-Taler-Operation`` header. The following operations are understood:

``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:

   -  ``X-Taler-Callback-Url``: URL that the wallet will visit when the
      reserve was created and the user has selected an exchange.

   -  ``X-Taler-Wt-Types``: JSON-encoded array of wire transfer types
      that this bank supports.

   -  ``X-Taler-Amount``: The amount that will be transferred to the
      reserve.

   -  ``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.

   The following header is optional:

   -  ``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.

   On successful reserve creation, the wallet will navigate to the
   callback URL (effectively requesting it with a GET) with the
   following additional request parameters:

   -  ``exchange``: The URL of the exchange selected by the user

   -  ``wire_details``: The wire details of the exchange.

   -  ``reserve_pub``: The reserve public key that the bank should
      transmit to the exchange when transmitting the funds.

``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 ``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.

.. _Bank_002dExchange-interaction:

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.

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 ``/admin/add/incoming``
API, providing those arguments it got along the ``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:
``execution_date`` (a operation’s timestamp), and ``transfer_details``
(just a "seed" to make unique the operation). See
https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions.

The polling mechanism is possbile thanks to the ``/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.

``GET /history``
   Ask the bank to return a list of money transactions related to a
   caller’s bank account.

   -  ``auth`` a string indicating the authentication method to use;
      only ``"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:
      ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
      will contain those plain text credentials.

   -  ``delta`` returns the first ``N`` records younger (older) than
      ``start`` if ``+N`` (``-N``) is specified.

   -  ``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.

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

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

Exchange pays merchant
~~~~~~~~~~~~~~~~~~~~~~

To allow the exchange to send payments to a merchant, the bank exposes
the ``/admin/add/incoming`` API to exchanges.

``POST /admin/add/incoming``
   Ask the bank to transfer money from the caller’s account to the
   receiver’s.

   -  ``auth`` a string indicating the authentication method to use;
      only ``"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:
      ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
      will contain those plain text credentials.

   -  ``amount`` a JSON object complying to the Taler amounts layout.
      Namely, this object must contain the following fields: ``value``
      (number), ``fraction`` (number), and ``currency`` (string).

   -  ``exchange_url`` a string indicating the calling exchange base
      URL. The bank will use this value to define wire transfers subject
      lines.

   -  ``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: ``'wtid exchange_url'``.

   -  ``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.

   -  ``credit_account`` bank account number that will receive the
      transfer. Tipically the merchant account number.