api-bank-conversion-info.rst (9208B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2014-2025 Taler Systems SA 5 6 TALER is free software; you can redistribute it and/or modify it under the 7 terms of the GNU Affero General Public License as published by the Free Software 8 Foundation; either version 2.1, or (at your option) any later version. 9 10 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 12 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 13 14 You should have received a copy of the GNU Affero General Public License along with 15 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 16 17 @author Marcello Stanisci 18 @author Christian Grothoff 19 @author Florian Dold 20 21 ========================= 22 Taler Conversion Info API 23 ========================= 24 25 This chapter describes the conversion info API. The conversion info API 26 is used by wallets for withdrawals that involve a currency conversion. 27 28 29 The current protocol version is **v2**. 30 31 * The wallet-core is currently targeting protocol version **v2**. 32 33 **Version history:** 34 35 * ``v2``: adds ``/rate`` endpoint 36 37 **Upcoming versions:** 38 39 * None anticipated. 40 41 **Ideas for future version:** 42 43 * ``vXXX``: marker for features not yet targeted for release 44 45 46 47 .. http:get:: /config 48 49 Return the protocol version and configuration information about the bank. 50 51 **Response:** 52 53 :http:statuscode:`200 OK`: 54 Response is a `ConversionConfig`. 55 :http:statuscode:`501 Not implemented`: 56 This server does not support conversion, client should check config response. 57 58 **Details:** 59 60 .. ts:def:: ConversionConfig 61 62 interface ConversionConfig { 63 // libtool-style representation of the Bank protocol version, see 64 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 65 // The format is "current:revision:age". 66 version: string; 67 68 // Name of the API. 69 name: "taler-conversion-info"; 70 71 // URN of the implementation (needed to interpret 'revision' in version). 72 // @since v4, may become mandatory in the future. 73 implementation?: string; 74 75 // Currency used by this bank. 76 regional_currency: string; 77 78 // How the bank SPA should render this currency. 79 regional_currency_specification: CurrencySpecification; 80 81 // External currency used during conversion. 82 fiat_currency: string; 83 84 // How the bank SPA should render this currency. 85 fiat_currency_specification: CurrencySpecification; 86 87 // Global exchange rate between the regional currency and the fiat 88 // currency of the banking system. Use /rate to get the user specific 89 // rate. 90 conversion_rate: ConversionRate; 91 } 92 93 .. http:get:: /rate 94 95 Since protocol **v2**. 96 97 This public endpoint allows clients to get the currenlty applied change rate between the regional currency and the fiat currency of the banking system for this exchange account. 98 Those informations should never be used to perform conversions use ``/cashin-rate`` and ``/cashout-rate`` instead. 99 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. 100 If ``cashin_ratio`` is zero, this means the account cannot cashin, and if ``cash_out`` ratio is zero, this means the account cannot cashout. 101 102 **Response:** 103 104 :http:statuscode:`200 OK`: 105 Response is a `ConversionRate`. 106 :http:statuscode:`501 Not implemented`: 107 This server does not support conversion. 108 109 .. _cashin-rates: 110 111 .. http:get:: /cashin-rate 112 113 This public endpoint allows clients to calculate 114 the exchange rate between the regional currency 115 and the fiat currency of the banking system. 116 117 This endpoint shows how the bank would apply the cash-in 118 ratio and fee to one input amount. Typically, wallets would 119 request this endpoint before creating withdrawals that involve 120 a currency conversion. 121 122 **Request:** 123 124 :query amount_debit: this is the amount that the user will get 125 deducted from their fiat bank account. 126 127 or 128 129 :query amount_credit: this is the amount that the user will receive 130 in their regional bank account. 131 132 **Response:** 133 134 :http:statuscode:`200 OK`: 135 Response is a `CashinConversionResponse`. 136 :http:statuscode:`400 Bad request`: 137 * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. 138 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount. 139 * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency. 140 :http:statuscode:`401 Unauthorized`: 141 Invalid credentials or missing rights. 142 :http:statuscode:`403 Forbidden`: 143 Missing rights. 144 :http:statuscode:`409 Conflict`: 145 The amount is too small to be converted because it produces an amount less than zero. 146 :http:statuscode:`501 Not implemented`: 147 This server does not support conversion, client should check config response. 148 149 **Details:** 150 151 .. ts:def:: CashinConversionResponse 152 153 interface CashinConversionResponse { 154 // Amount that the user will get deducted from their fiat 155 // bank account, according to the 'amount_credit' value. 156 amount_debit: Amount; 157 // Amount that the user will receive in their regional 158 // bank account, according to 'amount_debit'. 159 amount_credit: Amount; 160 } 161 162 .. _cashout-rates: 163 164 .. http:get:: /cashout-rate 165 166 This public endpoint allows clients to calculate 167 the exchange rate between the regional currency 168 and the fiat currency of the banking system. 169 170 This endpoint shows how the bank would apply the cash-out 171 ratio and fee to one input amount. Typically, frontends 172 ask this endpoint before creating cash-in operations. 173 174 **Request:** 175 176 :query amount_debit: this is the amount that the user will get 177 deducted from their regional bank account. 178 179 or 180 181 :query amount_credit: this is the amount that the user will receive 182 in their fiat bank account. 183 184 **Response:** 185 186 :http:statuscode:`200 OK`: 187 Response is a `CashoutConversionResponse`. 188 :http:statuscode:`400 Bad request`: 189 * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. 190 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount. 191 * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency. 192 :http:statuscode:`401 Unauthorized`: 193 Invalid credentials or missing rights. 194 :http:statuscode:`403 Forbidden`: 195 Missing rights. 196 :http:statuscode:`409 Conflict`: 197 The amount is too small to be converted because it produces an amount less than zero. 198 :http:statuscode:`501 Not implemented`: 199 This server does not support conversion, client should check config response. 200 201 **Details:** 202 203 .. ts:def:: CashoutConversionResponse 204 205 interface CashoutConversionResponse { 206 // Amount that the user will get deducted from their regional 207 // bank account, according to the 'amount_credit' value. 208 amount_debit: Amount; 209 // Amount that the user will receive in their fiat 210 // bank account, according to 'amount_debit'. 211 amount_credit: Amount; 212 } 213 214 .. http:post:: /conversion-rate 215 216 This endpoint allows the administrator to update the global exchange rate between the regional currency and the fiat currency of the banking system. Individual users can have different rate if they are part of an conversion rate classe. 217 218 The conversion is calculated as follows: ``(amount * ratio - fee) / tiny_amount``. 219 220 Only available to the administrator. 221 222 **Request:** 223 224 .. ts:def:: ConversionRate 225 226 interface ConversionRate { 227 // Minimum fiat amount authorised for cashin before conversion 228 cashin_min_amount: Amount; 229 230 // Exchange rate to buy regional currency from fiat 231 cashin_ratio: DecimalNumber; 232 233 // Regional amount fee to subtract after applying the cashin ratio. 234 cashin_fee: Amount; 235 236 // Smallest possible regional amount, converted amount is rounded to this amount 237 cashin_tiny_amount: Amount; 238 239 // Rounding mode used during cashin conversion 240 cashin_rounding_mode: "zero" | "up" | "nearest"; 241 242 // Minimum regional amount authorised for cashout before conversion 243 cashout_min_amount: Amount; 244 245 // Exchange rate to sell regional currency for fiat 246 cashout_ratio: DecimalNumber; 247 248 // Fiat amount fee to subtract after applying the cashout ratio. 249 cashout_fee: Amount; 250 251 // Smallest possible fiat amount, converted amount is rounded to this amount 252 cashout_tiny_amount: Amount; 253 254 // Rounding mode used during cashout conversion 255 cashout_rounding_mode: "zero" | "up" | "nearest"; 256 } 257 258 **Response:** 259 260 :http:statuscode:`204 No content`: 261 Operation successful. 262 :http:statuscode:`401 Unauthorized`: 263 Invalid credentials or missing rights. 264 :http:statuscode:`403 Forbidden`: 265 Missing rights. 266 :http:statuscode:`501 Not implemented`: 267 This server does not support conversion, client should check config response.