blob: 4131a28a4fadb23128c91a35e6e0e3f0d5e9c573 (
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
|
..
This file is part of GNU TALER.
Copyright (C) 2014-2023 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 Marcello Stanisci
@author Christian Grothoff
==========================
Taler Bank Integration API
==========================
This chapter describe the APIs that banks need to offer towards Taler wallets
to tightly integrate with GNU Taler.
.. contents:: Table of Contents
.. http:get:: /config
Return the protocol version and configuration information about the bank.
This specification corresponds to ``current`` protocol being version **2**.
**Response:**
:http:statuscode:`200 OK`:
The exchange responds with a `IntegrationConfig` object. This request should
virtually always be successful.
**Details:**
.. ts:def:: IntegrationConfig
interface IntegrationConfig {
// Name of the API.
name: "taler-bank-integration";
// libtool-style representation of the Bank protocol version, see
// https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
// The format is "current:revision:age".
version: string;
// URN of the implementation (needed to interpret 'revision' in version).
// @since v2, may become mandatory in the future.
implementation?: string;
// Currency used by this bank.
currency: string;
// How the bank SPA should render this currency.
currency_specification: CurrencySpecification;
}
-----------
Withdrawing
-----------
Withdrawals with a Taler-integrated bank are based on withdrawal operations.
Some user interaction (on the bank's website or a Taler-enabled ATM) creates a
withdrawal operation record in the bank's database. The wallet can use a unique identifier
for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation.
.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``.
**Request:**
:query long_poll_ms:
*Optional.* If specified, the bank will wait up to ``long_poll_ms``
milliseconds for operationt state to be different from ``old_state`` before sending the HTTP
response. A client must never rely on this behavior, as the bank may
return a response immediately.
:query old_state:
*Optional.* Default to "pending".
**Response:**
:http:statuscode:`200 OK`:
The withdrawal operation is known to the bank, and details are given
in the `BankWithdrawalOperationStatus` response body.
:http:statuscode:`404 Not found`:
The operation was not found
**Details:**
.. ts:def:: BankWithdrawalOperationStatus
export class BankWithdrawalOperationStatus {
// Current status of the operation
// pending: the operation is pending parameters selection (exchange and reserve public key)
// selected: the operations has been selected and is pending confirmation
// aborted: the operation has been aborted
// confirmed: the transfer has been confirmed and registered by the bank
// Since protocol v1.
status: "pending" | "selected" | "aborted" | "confirmed";
// Amount that will be withdrawn with this operation
// (raw amount without fee considerations).
amount: Amount;
// Bank account of the customer that is withdrawing, as a
// ``payto`` URI.
sender_wire?: string;
// Suggestion for an exchange given by the bank.
suggested_exchange?: string;
// URL that the user needs to navigate to in order to
// complete some final confirmation (e.g. 2FA).
// Only applicable when ``status`` is ``selected`` or ``pending``.
// It may contain withdrawal operation id
confirm_transfer_url?: string;
// Wire transfer types supported by the bank.
wire_types: string[];
// Reserve public key selected by the exchange,
// only non-null if ``status`` is ``selected`` or ``confirmed``.
// Since protocol v1.
selected_reserve_pub?: string;
// Exchange account selected by the wallet
// only non-null if ``status`` is ``selected`` or ``confirmed``.
// Since protocol v1.
selected_exchange_account?: string;
// Deprecated field since protocol v1 use ``status`` instead
// Indicates whether the withdrawal was aborted.
aborted: boolean;
// Deprecated field since protocol v1 use ``status`` instead
// Has the wallet selected parameters for the withdrawal operation
// (exchange and reserve public key) and successfully sent it
// to the bank?
selection_done: boolean;
// Deprecated field since protocol v1 use ``status`` instead
// The transfer has been confirmed and registered by the bank.
// Does not guarantee that the funds have arrived at the exchange already.
transfer_done: boolean;
}
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
**Request:**
.. ts:def:: BankWithdrawalOperationPostRequest
interface BankWithdrawalOperationPostRequest {
// Reserve public key.
reserve_pub: string;
// Payto address of the exchange selected for the withdrawal.
selected_exchange: string;
}
**Response:**
:http:statuscode:`200 OK`:
The bank has accepted the withdrawal operation parameters chosen by the wallet.
The response is a `BankWithdrawalOperationPostResponse`.
:http:statuscode:`404 Not found`:
The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``.
:http:statuscode:`409 Conflict`:
* ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` :
The wallet selected a different exchange or reserve public key under the same withdrawal ID.
* ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key is already used.
* ``TALER_EC_BANK_UNKNOWN_ACCOUNT`` : the selected exchange account was not found.
* ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE`` : the selected account is not an exchange.
**Details:**
.. ts:def:: BankWithdrawalOperationPostResponse
interface BankWithdrawalOperationPostResponse {
// Current status of the operation
// pending: the operation is pending parameters selection (exchange and reserve public key)
// selected: the operations has been selected and is pending confirmation
// aborted: the operation has been aborted
// confirmed: the transfer has been confirmed and registered by the bank
status: "selected" | "aborted" | "confirmed";
// URL that the user needs to navigate to in order to
// complete some final confirmation (e.g. 2FA).
//
// Only applicable when ``status`` is ``selected`` or ``pending``.
// It may contain withdrawal operation id
confirm_transfer_url?: string;
// Deprecated field use ``status`` instead
// The transfer has been confirmed and registered by the bank.
// Does not guarantee that the funds have arrived at the exchange already.
transfer_done: boolean;
}
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted
operation.
Since protocol v2.
**Response:**
:http:statuscode:`204 No content`:
The withdrawal operation has been aborted.
:http:statuscode:`404 Not found`:
The withdrawal operation was not found.
:http:statuscode:`409 Conflict`:
The withdrawal operation has been confirmed previously and can't be aborted.
|
