summaryrefslogtreecommitdiff
path: root/core/api-bank-access.rst
blob: 0df13f4ba9b15429ac891f3f8c6d462293532a75 (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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
..
  This file is part of GNU TALER.

  Copyright (C) 2014-2020 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Florian Dold

=====================
Taler Bank Access API
=====================

This chapter describes the API that the GNU Taler demonstrator bank offers to access accounts.

This API differs from the "Bank Integration API" in that it provides advanced API access to accounts, as opposed
to enabling wallets to withdraw with a better user experience ("tight integration").


------------------------
Accounts and Withdrawals
------------------------

.. http:get:: ${BANK_API_BASE_URL}/public-accounts

  Show those accounts whose histories are publicly visible.  For example,
  accounts from donation receivers.  As such, this request is unauthenticated.

  **Response**

  **Details**

  .. ts:def:: PublicAccountsResponse

    interface PublicAccountsResponse {
      publicAccounts: PublicAccount[]
    }

  .. ts:def:: PublicAccount

    interface PublicAccount {
      iban: string;
      balance: string;
      // The account name _and_ the username of the
      // Sandbox customer that owns such a bank account.
      accountLabel: string;
    }

The following endpoints require HTTP "Basic" authentication with the account
name and account password, at least in the GNU Taler demo bank implementation.


.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}

  Request the current balance of an account.  (New: ) In case of a public bank
  account, no authentication is required.

  **Response**

  **Details**

  .. ts:def:: BankAccountBalanceResponse

    interface Balance {
      amount: Amount;
      credit_debit_indicator: "credit" | "debit";
    }

    interface BankAccountBalanceResponse {
      // Available balance on the account.
      balance: Balance;

      // payto://-URI of the account. (New)
      paytoUri: string;

      // Number indicating the max debit allowed for the requesting user.
      debitThreshold: String;
    }


.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals

  Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.

  **Request**

  .. ts:def:: BankAccountCreateWithdrawalRequest

    interface BankAccountCreateWithdrawalRequest {
      // Amount to withdraw.
      amount: Amount;
    }

  **Response**

  .. ts:def:: BankAccountCreateWithdrawalResponse

    interface BankAccountCreateWithdrawalResponse {
      // ID of the withdrawal, can be used to view/modify the withdrawal operation.
      withdrawal_id: string;

      // URI that can be passed to the wallet to initiate the withdrawal.
      taler_withdraw_uri: string;
    }

  :http:statuscode:`403 Forbidden`:
    The operation was rejected due to insufficient funds.

.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}

  Query the status of a withdrawal operation.

  **Response**

  **Details**

  .. ts:def:: BankAccountGetWithdrawalResponse

    interface BankAccountGetWithdrawalResponse {
      // Amount that will be withdrawn with this withdrawal operation.
      amount: Amount;

      // Was the withdrawal aborted?
      aborted: boolean;

      // Has the withdrawal been confirmed by the bank?
      // The wire transfer for a withdrawal is only executed once
      // both ``confirmation_done`` is ``true`` and ``selection_done`` is ``true``.
      confirmation_done: boolean;

      // Did the wallet select reserve details?
      selection_done: boolean;

      // Reserve public key selected by the exchange,
      // only non-null if ``selection_done`` is ``true``.
      selected_reserve_pub: string | null;

      // Exchange account selected by the wallet, or by the bank
      // (with the default exchange) in case the wallet did not provide one
      // through the Integration API.
      selected_exchange_account: string | null;
    }


.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort

  Abort a withdrawal operation.  Has no effect on an already aborted withdrawal operation.

  :http:statuscode:`200 OK`: The withdrawal operation has been aborted.  The response is an empty JSON object.
  :http:statuscode:`409 Conflict`:  The reserve operation has been confirmed previously and can't be aborted.


.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm

  Confirm a withdrawal operation.  Has no effect on an already confirmed withdrawal operation.
  This call is responsible of wiring the funds to the exchange.

  **Response**

  :http:statuscode:`200 OK`:
     The withdrawal operation has been confirmed.  The response is an empty JSON object.
  :http:statuscode:`409 Conflict`:
     The withdrawal has been aborted previously and can't be confirmed.
  :http:statuscode:`422 Unprocessable Entity` (New):
     The withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.

------------
Transactions
------------

.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions

   Retrieve a subset of transactions related to $account_name.  Without
   query parameters, it returns the last 5 transactions.

   **Request**

   :query page: page number starting from 1.  Page 1 has the latest transactions
     and 1 is the default value.
   :query size: how many transactions per page.  It must be at least 1 and defaults to 5.
   :query from_ms: Optional.  Filters the results to transactions *from* this
     timestamp in milliseconds
   :query until_ms: Optional.  Filters the results to transactions *until* this
     timestamp in milliseconds

   **Response**

   .. ts:def:: BankAccountTransactionsResponse

     interface BankAccountTransactionsResponse {
       transactions: BankAccountTransactionInfo[];
     }

.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}

   **Response**

   Retrieve the transaction whose identifier is ``transaction_id``,
   in the following format:

   .. ts:def:: BankAccountTransactionInfo

     interface BankAccountTransactionInfo {

       creditorIban: string;
       creditorBic: string; // Optional
       creditorName: string;

       debtorIban: string;
       debtorBic: string;
       debtorName: string;

       amount: number;
       currency: string;
       subject: string;

       // Transaction unique ID.  Matches
       // $transaction_id from the URI.
       uid: string;
       direction: "DBIT" | "CRDT";
       date: string; // milliseconds since the Unix epoch
     }


.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions

   Create a new transaction where the bank account with the label ``account_name`` is **debited**.

   **Request**

   .. ts:def:: BankAccountTransactionCreate

      interface CreateBankAccountTransactionCreate {

        // Address in the Payto format of the wire transfer receiver.
        // It needs at least the 'message' query string parameter.
        paytoUri: string;

        // Transaction amount (in the $currency:x.y format), optional.
        // However, when not given, its value must occupy the 'amount'
        // query string parameter of the 'payto' field.  In case it
        // is given in both places, the paytoUri's takes the precedence.
        amount: string;
      }

   **Response**

   :http:statuscode:`200 OK`:
      the transaction has been created.

   :http:statuscode:`400 Bad Request`:
      the request was invalid or the payto://-URI used unacceptable features.

.. http:delete:: ${BANK_API_BASE_URL}/accounts/${account_name}

   Delete the bank account (and the customer entry) from the database.
   Note, customer usernames and bank accounts have the same value.

----------------------
Registration (Testing)
----------------------

.. http:post:: ${BANK_API_BASE_URL}/testing/register

  Create a new bank account.  This endpoint should be disabled for most deployments, but is useful
  for automated testing / integration tests.

  **Request**

  .. ts:def:: BankRegistrationRequest

    interface BankRegistrationRequest {
      username: string;

      password: string;
    }


  **Response**

  :http:statuscode:`200 OK`:  Registration was successful.