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
|
..
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
@author Florian Dold
=========================
Taler Conversion Info API
=========================
This chapter describes the conversion info API. The conversion info API
is used by wallets for withdrawals that involve a currency conversion.
.. contents:: Table of Contents
.. http:get:: /config
Get configuration information about the bank.
**Response:**
:http:statuscode:`200 OK`:
Response is a `ConversionConfig`.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
**Details:**
.. ts:def:: ConversionConfig
interface ConversionConfig {
// 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;
// Name of the API.
name: "taler-conversion-info";
// URN of the implementation (needed to interpret 'revision' in version).
// @since v4, may become mandatory in the future.
implementation?: string;
// Currency used by this bank.
regional_currency: string;
// How the bank SPA should render this currency.
regional_currency_specification: CurrencySpecification;
// External currency used during conversion.
fiat_currency: string;
// How the bank SPA should render this currency.
fiat_currency_specification: CurrencySpecification;
// Additional information on conversion rates.
// Those informations should never be used to perform conversions,
// use /cashin-rate or /cashout-rate instead.
// Conversion rates can change at any time. Clients must deal with
// any resulting errors and call /cashin-rate or /cashout-rate again
// to use the new rates.
conversion_rate: ConversionRate;
}
.. http:get:: /cashin-rate
This public endpoint allows clients to calculate
the exchange rate between the regional currency
and the fiat currency of the banking system.
This endpoint shows how the bank would apply the cash-in
ratio and fee to one input amount. Typically, wallets would
request this endpoint before creating withdrawals that involve
a currency conversion.
**Request:**
:query amount_debit: this is the amount that the user will get
deducted from their fiat bank account.
or
:query amount_credit: this is the amount that the user will receive
in their regional bank account.
**Response:**
:http:statuscode:`200 OK`:
Response is a `CashinConversionResponse`.
:http:statuscode:`400 Bad request`:
* ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided.
* ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount.
* ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency.
:http:statuscode:`409 Conflict`:
The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
**Details:**
.. ts:def:: CashinConversionResponse
interface CashinConversionResponse {
// Amount that the user will get deducted from their fiat
// bank account, according to the 'amount_credit' value.
amount_debit: Amount;
// Amount that the user will receive in their regional
// bank account, according to 'amount_debit'.
amount_credit: Amount;
}
.. http:get:: /cashout-rate
This public endpoint allows clients to calculate
the exchange rate between the regional currency
and the fiat currency of the banking system.
This endpoint shows how the bank would apply the cash-out
ratio and fee to one input amount. Typically, frontends
ask this endpoint before creating cash-in operations.
**Request:**
:query amount_debit: this is the amount that the user will get
deducted from their regional bank account.
or
:query amount_credit: this is the amount that the user will receive
in their fiat bank account.
**Response:**
:http:statuscode:`200 OK`:
Response is a `CashoutConversionResponse`.
:http:statuscode:`400 Bad request`:
* ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided.
* ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount.
* ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency.
:http:statuscode:`409 Conflict`:
The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
**Details:**
.. ts:def:: CashoutConversionResponse
interface CashoutConversionResponse {
// Amount that the user will get deducted from their regional
// bank account, according to the 'amount_credit' value.
amount_debit: Amount;
// Amount that the user will receive in their fiat
// bank account, according to 'amount_debit'.
amount_credit: Amount;
}
.. http:post:: /conversion-rate
This endpoint allows the administrator to update
the exchange rate between the regional currency
and the fiat currency of the banking system.
**Request:**
.. ts:def:: ConversionRate
interface ConversionRate {
// Exchange rate to buy regional currency from fiat
cashin_ratio: DecimalNumber;
// Regional amount fee to subtract after applying the cashin ratio.
cashin_fee: Amount;
// Minimum fiat amount authorised for cashin before conversion
cashin_min_amount: Amount;
// Smallest possible regional amount, converted amount is rounded to this amount
cashin_tiny_amount: Amount;
// Rounding mode used during cashin conversion
cashin_rounding_mode: "zero" | "up" | "nearest";
// Exchange rate to sell regional currency for fiat
cashout_ratio: DecimalNumber;
// Fiat amount fee to subtract after applying the cashout ratio.
cashout_fee: Amount;
// Minimum regional amount authorised for cashout before conversion
cashout_min_amount: Amount;
// Smallest possible fiat amount, converted amount is rounded to this amount
cashout_tiny_amount: Amount;
// Rounding mode used during cashout conversion
cashout_rounding_mode: "zero" | "up" | "nearest";
}
**Response:**
:http:statuscode:`204 No content`:
Operation successful.
:http:statuscode:`401 Unauthorized`:
Invalid credentials or missing rights.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
|
