summaryrefslogtreecommitdiff
path: root/core/api-bank-access.rst
blob: 456211b74cbecd53e85e7658ec82d2babda33dea (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
..
  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 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 General Public License for more details.

  You should have received a copy of the GNU 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
------------------------

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.

  **Response**

  **Details**

  .. ts:def:: BankAccountBalanceResponse

    interface BankAccountBalanceResponse {
      // Available balance on the account.
      balance: {
        amount: Amount;
        credit_debit_indicator: "credit" | "debit";
      };
    }


.. 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: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 exchange,
      // only non-null if selection_done is 'true'
      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.

  **Response**

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




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