api-bank-integration.rst (11315B)
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 20 ========================== 21 Taler Bank Integration API 22 ========================== 23 24 This chapter describe the APIs that banks need to offer towards Taler wallets 25 to tightly integrate with GNU Taler. 26 27 28 --------------- 29 Version History 30 --------------- 31 32 The current protocol version is **v5**. 33 34 * The wallet-core is currently targeting protocol version **v4**. 35 36 **Version history:** 37 38 * ``v5``: adds ``no_amount_to_wallet`` flag to the WOPID status 39 40 **Upcoming versions:** 41 42 * ``vSHORT``: support for short wire transfer subjects? 43 * ``vPERIODIC``: support for periodic wire transfers? 44 45 **Ideas for future version:** 46 47 * ``vXXX``: marker for features not yet targeted for release 48 49 50 .. http:get:: /config 51 52 Return the protocol version and configuration information about the bank. 53 54 **Response:** 55 56 :http:statuscode:`200 OK`: 57 The exchange responds with a `IntegrationConfig` object. This request should 58 virtually always be successful. 59 60 **Details:** 61 62 .. ts:def:: IntegrationConfig 63 64 interface IntegrationConfig { 65 // Name of the API. 66 name: "taler-bank-integration"; 67 68 // libtool-style representation of the Bank protocol version, see 69 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 70 // 71 // The format is "current:revision:age". 72 version: string; 73 74 // URN of the implementation (needed to interpret 'revision' in version). 75 // @since **v2**, may become mandatory in the future. 76 implementation?: string; 77 78 // Currency used by this bank. 79 currency: string; 80 81 // How the bank SPA should render this currency. 82 currency_specification: CurrencySpecification; 83 } 84 85 86 .. _wallet-wopid-withdrawing: 87 88 ----------- 89 Withdrawing 90 ----------- 91 92 Withdrawals with a Taler-integrated bank are based on withdrawal operations. 93 Some user interaction (on the bank's websitei) creates a 94 withdrawal operation record in the bank's database. The wallet can use a unique identifier 95 for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation. 96 97 .. http:get:: /withdrawal-operation/$WITHDRAWAL_ID 98 99 Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``. 100 101 **Request:** 102 103 :query timeout_ms: *Optional.* 104 Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for operation state to be different from ``old_state``. Since protocol **v3**. 105 :query old_state: 106 *Optional.* Defaults to "pending". 107 :query long_poll_ms: *Optional.* 108 Deprecated in protocol **v3**. Use *timeout_ms* instead. 109 110 **Response:** 111 112 :http:statuscode:`200 OK`: 113 The withdrawal operation is known to the bank, and details are given 114 in the `BankWithdrawalOperationStatus` response body. 115 :http:statuscode:`404 Not found`: 116 The operation was not found. 117 118 **Details:** 119 120 .. ts:def:: BankWithdrawalOperationStatus 121 122 interface BankWithdrawalOperationStatus { 123 // Current status of the operation 124 // pending: the operation is pending parameters selection (exchange and reserve public key) 125 // selected: the operations has been selected and is pending confirmation 126 // aborted: the operation has been aborted 127 // confirmed: the transfer has been confirmed and registered by the bank 128 // @since **v1** 129 status: "pending" | "selected" | "aborted" | "confirmed"; 130 131 // Currency used for the withdrawal. 132 // MUST be present when amount is absent. 133 // @since **v2**, may become mandatory in the future. 134 currency?: string; 135 136 // Amount that will be withdrawn with this operation 137 // (raw amount without fee considerations). Only 138 // given once the amount is fixed and cannot be changed. 139 // Optional since **v4**. 140 amount?: Amount; 141 142 // Suggestion for the amount to be withdrawn with this 143 // operation. Given if a suggestion was made but the 144 // user may still change the amount. 145 // Optional since **v4**. 146 suggested_amount?: Amount; 147 148 // Minimum amount that the wallet can choose to withdraw. 149 // Only applicable when the amount is not fixed. 150 // @since **v4**. 151 min_amount?: Amount; 152 153 // Maximum amount that the wallet can choose to withdraw. 154 // Only applicable when the amount is not fixed. 155 // @since **v4**. 156 max_amount?: Amount; 157 158 // The non-Taler card fees the customer will have 159 // to pay to the bank / payment service provider 160 // they are using to make the withdrawal in addition 161 // to the amount. 162 // @since **v4** 163 card_fees?: Amount; 164 165 // Bank account of the customer that is debiting, as a 166 // full RFC 8905 ``payto`` URI. 167 sender_wire?: string; 168 169 // Base URL of the suggested exchange. The bank may have 170 // neither a suggestion nor a requirement for the exchange. 171 // This value is typically set in the bank's configuration. 172 suggested_exchange?: string; 173 174 // Base URL of an exchange that must be used. Optional, 175 // not given *unless* a particular exchange is mandatory. 176 // This value is typically set in the bank's configuration. 177 // @since **v4** 178 required_exchange?: string; 179 180 // URL that the user needs to navigate to in order to 181 // complete some final confirmation (e.g. 2FA). 182 // Only applicable when ``status`` is ``selected`` or ``pending``. 183 // It may contain the withdrawal operation id. 184 confirm_transfer_url?: string; 185 186 // Wire transfer types supported by the bank. 187 wire_types: string[]; 188 189 // Reserve public key selected by the exchange, 190 // only non-null if ``status`` is ``selected`` or ``confirmed``. 191 // @since **v1** 192 selected_reserve_pub?: EddsaPublicKey; 193 194 // Exchange account selected by the wallet; 195 // only non-null if ``status`` is ``selected`` or ``confirmed``. 196 // @since **v1** 197 selected_exchange_account?: string; 198 199 // If true, tells the wallet not to allow the user to 200 // specify an amount to withdraw and to not provide 201 // any amount when registering with the withdrawal 202 // operation. The amount to withdraw will be set 203 // by the final ``/withdrawals/$WITHDRAWAL_ID/confirm`` step. 204 // @since **v5** 205 no_amount_to_wallet?: boolean; 206 207 // @deprecated since **v1**, use ``status`` instead 208 // Indicates whether the withdrawal was aborted. 209 aborted: boolean; 210 211 // @deprecated since **v1**, use ``status`` instead 212 // Has the wallet selected parameters for the withdrawal operation 213 // (exchange and reserve public key) and successfully sent it 214 // to the bank? 215 selection_done: boolean; 216 217 // @deprecated since **v1**, use ``status`` instead 218 // The transfer has been confirmed and registered by the bank. 219 // Does not guarantee that the funds have arrived at the exchange already. 220 transfer_done: boolean; 221 } 222 223 224 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID 225 226 This endpoint is used by the GNU Taler wallet to supply additional 227 details needed to complete a withdraw operation. 228 229 **Request:** 230 231 .. ts:def:: BankWithdrawalOperationPostRequest 232 233 interface BankWithdrawalOperationPostRequest { 234 235 // Reserve public key that should become the wire transfer 236 // subject to fund the withdrawal. 237 reserve_pub: EddsaPublicKey; 238 239 // Full RFC 8905 (payto) address of the exchange account to be 240 // credited for the withdrawal. 241 selected_exchange: string; 242 243 // Selected amount to be transferred. Optional if the 244 // backend already knows the amount. 245 // @since **v4** 246 amount?: Amount; 247 } 248 249 **Response:** 250 251 :http:statuscode:`200 OK`: 252 The bank has accepted the withdrawal operation parameters chosen by the wallet. 253 The response is a `BankWithdrawalOperationPostResponse`. 254 :http:statuscode:`404 Not found`: 255 The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``. 256 :http:statuscode:`409 Conflict`: 257 * ``TALER_EC_BANK_UPDATE_ABORT_CONFLICT`` : the withdrawal has been aborted previously and can't be modified. 258 * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT``: 259 The wallet selected a different exchange or reserve public key under the same withdrawal ID. 260 * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the reserve public key is already used. 261 * ``TALER_EC_BANK_UNKNOWN_ACCOUNT``: the selected exchange account was not found. 262 * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE``: the selected account is not an exchange. 263 * ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work for this 264 withdrawal (since **v4**). 265 * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds or the amount is too low or too high (since **v4**). 266 267 **Details:** 268 269 .. ts:def:: BankWithdrawalOperationPostResponse 270 271 interface BankWithdrawalOperationPostResponse { 272 // Current status of the operation 273 // pending: the operation is pending parameters selection (exchange and reserve public key) 274 // selected: the operations has been selected and is pending confirmation 275 // aborted: the operation has been aborted 276 // confirmed: the transfer has been confirmed and registered by the bank 277 status: "selected" | "aborted" | "confirmed"; 278 279 // URL that the user needs to navigate to in order to 280 // complete some final confirmation (e.g. 2FA). 281 // 282 // Only applicable when ``status`` is ``selected`` or ``pending``. 283 // It may contain withdrawal operation id 284 confirm_transfer_url?: string; 285 286 // @deprecated since **v1**, use ``status`` instead 287 // The transfer has been confirmed and registered by the bank. 288 // Does not guarantee that the funds have arrived at the exchange already. 289 transfer_done: boolean; 290 } 291 292 293 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort 294 295 Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted 296 operation. This endpoint can be used by the wallet if the user aborts 297 the transaction, ensuring that the operation is also aborted at the 298 bank. 299 300 Since protocol **v2**. 301 302 **Request:** 303 304 The request body is empty. 305 306 **Response:** 307 308 :http:statuscode:`204 No content`: 309 The withdrawal operation has been aborted. 310 :http:statuscode:`404 Not found`: 311 The withdrawal operation was not found. 312 :http:statuscode:`409 Conflict`: 313 The withdrawal operation has been confirmed previously and 314 can't be aborted.