api-bank-conversion-info.rst (8946B)
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 .. contents:: Table of Contents 30 31 .. http:get:: /config 32 33 Return the protocol version and configuration information about the bank. 34 This specification corresponds to ``current`` protocol being **v2**. 35 36 **Response:** 37 38 :http:statuscode:`200 OK`: 39 Response is a `ConversionConfig`. 40 :http:statuscode:`501 Not implemented`: 41 This server does not support conversion, client should check config response. 42 43 **Details:** 44 45 .. ts:def:: ConversionConfig 46 47 interface ConversionConfig { 48 // libtool-style representation of the Bank protocol version, see 49 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 50 // The format is "current:revision:age". 51 version: string; 52 53 // Name of the API. 54 name: "taler-conversion-info"; 55 56 // URN of the implementation (needed to interpret 'revision' in version). 57 // @since v4, may become mandatory in the future. 58 implementation?: string; 59 60 // Currency used by this bank. 61 regional_currency: string; 62 63 // How the bank SPA should render this currency. 64 regional_currency_specification: CurrencySpecification; 65 66 // External currency used during conversion. 67 fiat_currency: string; 68 69 // How the bank SPA should render this currency. 70 fiat_currency_specification: CurrencySpecification; 71 72 // Global exchange rate between the regional currency and the fiat 73 // currency of the banking system. Use /rate to get the user specific 74 // rate. 75 conversion_rate: ConversionRate; 76 } 77 78 .. http:get:: /rate 79 80 Since protocol **v2**. 81 82 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. 83 Those informations should never be used to perform conversions use /cashin-rate and /cashout-rate instead. 84 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. 85 If cashin_ratio is zero, this means the account cannot cashin, and if cash_out ratio is zero, this means the account cannot cashout. 86 87 **Response:** 88 89 :http:statuscode:`200 OK`: 90 Response is a `ConversionRate`. 91 :http:statuscode:`501 Not implemented`: 92 This server does not support conversion. 93 94 .. http:get:: /cashin-rate 95 96 This public endpoint allows clients to calculate 97 the exchange rate between the regional currency 98 and the fiat currency of the banking system. 99 100 This endpoint shows how the bank would apply the cash-in 101 ratio and fee to one input amount. Typically, wallets would 102 request this endpoint before creating withdrawals that involve 103 a currency conversion. 104 105 **Request:** 106 107 :query amount_debit: this is the amount that the user will get 108 deducted from their fiat bank account. 109 110 or 111 112 :query amount_credit: this is the amount that the user will receive 113 in their regional bank account. 114 115 **Response:** 116 117 :http:statuscode:`200 OK`: 118 Response is a `CashinConversionResponse`. 119 :http:statuscode:`400 Bad request`: 120 * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. 121 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount. 122 * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency. 123 :http:statuscode:`401 Unauthorized`: 124 Invalid credentials or missing rights. 125 :http:statuscode:`403 Forbidden`: 126 Missing rights. 127 :http:statuscode:`409 Conflict`: 128 The amount is too small to be converted because it produces an amount less than zero. 129 :http:statuscode:`501 Not implemented`: 130 This server does not support conversion, client should check config response. 131 132 **Details:** 133 134 .. ts:def:: CashinConversionResponse 135 136 interface CashinConversionResponse { 137 // Amount that the user will get deducted from their fiat 138 // bank account, according to the 'amount_credit' value. 139 amount_debit: Amount; 140 // Amount that the user will receive in their regional 141 // bank account, according to 'amount_debit'. 142 amount_credit: Amount; 143 } 144 145 .. http:get:: /cashout-rate 146 147 This public endpoint allows clients to calculate 148 the exchange rate between the regional currency 149 and the fiat currency of the banking system. 150 151 This endpoint shows how the bank would apply the cash-out 152 ratio and fee to one input amount. Typically, frontends 153 ask this endpoint before creating cash-in operations. 154 155 **Request:** 156 157 :query amount_debit: this is the amount that the user will get 158 deducted from their regional bank account. 159 160 or 161 162 :query amount_credit: this is the amount that the user will receive 163 in their fiat bank account. 164 165 **Response:** 166 167 :http:statuscode:`200 OK`: 168 Response is a `CashoutConversionResponse`. 169 :http:statuscode:`400 Bad request`: 170 * ``TALER_EC_GENERIC_PARAMETER_MISSING`` : none of the parameters have been provided. 171 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` : both of the parameters have been provided or one of them is not a valid Taler amount. 172 * ``TALER_EC_GENERIC_CURRENCY_MISMATCH`` : the parameter is in the wrong currency. 173 :http:statuscode:`401 Unauthorized`: 174 Invalid credentials or missing rights. 175 :http:statuscode:`403 Forbidden`: 176 Missing rights. 177 :http:statuscode:`409 Conflict`: 178 The amount is too small to be converted because it produces an amount less than zero. 179 :http:statuscode:`501 Not implemented`: 180 This server does not support conversion, client should check config response. 181 182 **Details:** 183 184 .. ts:def:: CashoutConversionResponse 185 186 interface CashoutConversionResponse { 187 // Amount that the user will get deducted from their regional 188 // bank account, according to the 'amount_credit' value. 189 amount_debit: Amount; 190 // Amount that the user will receive in their fiat 191 // bank account, according to 'amount_debit'. 192 amount_credit: Amount; 193 } 194 195 .. http:post:: /conversion-rate 196 197 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. 198 199 The conversion is calculated as follows: ``(amount * ratio - fee) / tiny_amount``. 200 201 Only available to the administrator. 202 203 **Request:** 204 205 .. ts:def:: ConversionRate 206 207 interface ConversionRate { 208 // Minimum fiat amount authorised for cashin before conversion 209 cashin_min_amount: Amount; 210 211 // Exchange rate to buy regional currency from fiat 212 cashin_ratio: DecimalNumber; 213 214 // Regional amount fee to subtract after applying the cashin ratio. 215 cashin_fee: Amount; 216 217 // Smallest possible regional amount, converted amount is rounded to this amount 218 cashin_tiny_amount: Amount; 219 220 // Rounding mode used during cashin conversion 221 cashin_rounding_mode: "zero" | "up" | "nearest"; 222 223 // Minimum regional amount authorised for cashout before conversion 224 cashout_min_amount: Amount; 225 226 // Exchange rate to sell regional currency for fiat 227 cashout_ratio: DecimalNumber; 228 229 // Fiat amount fee to subtract after applying the cashout ratio. 230 cashout_fee: Amount; 231 232 // Smallest possible fiat amount, converted amount is rounded to this amount 233 cashout_tiny_amount: Amount; 234 235 // Rounding mode used during cashout conversion 236 cashout_rounding_mode: "zero" | "up" | "nearest"; 237 } 238 239 **Response:** 240 241 :http:statuscode:`204 No content`: 242 Operation successful. 243 :http:statuscode:`401 Unauthorized`: 244 Invalid credentials or missing rights. 245 :http:statuscode:`403 Forbidden`: 246 Missing rights. 247 :http:statuscode:`501 Not implemented`: 248 This server does not support conversion, client should check config response.